Convert opencode transcripts to otel (or agent) traces
Update Agent Trace plan with TypeScript and configurable line length
- Switch from Rust to TypeScript implementation (src/commands/agent-trace.ts)
- Clarify tool.name mapping: tool = what agent executes (EditFile, RunShell, etc.)
- User chats map to human contributor type, AI chats to ai
- Add configurable line_length (default 100) for line estimation
- Use ceil(content_length / line_length) for line count calculation
- Add TypeScript dependencies (commander, types)
- Update migration path for TypeScript build process
+777
+777
doc/PLAN-cursor-trace.md
+777
doc/PLAN-cursor-trace.md
···
1
+
# Agent Trace Support for exp2span
2
+
3
+
## Overview
4
+
5
+
This document proposes adding Agent Trace (https://agent-trace.dev/) support to exp2span. Agent Trace is an open specification for tracking AI-generated code, providing vendor-neutral attribution for code contributions.
6
+
7
+
**Status**: Draft Proposal
8
+
**Date**: February 2026
9
+
10
+
## Current State
11
+
12
+
exp2span currently:
13
+
- Parses opencode markdown logs into GenAiSpan structures
14
+
- Converts to OpenTelemetry spans using MCP semantic conventions
15
+
- Exports to OTLP collectors (HTTP/gRPC)
16
+
- Implements reverse-threading of span timestamps from log's `updated` field
17
+
18
+
## Goals
19
+
20
+
1. **Dual Output**: Support both Agent Trace and OTLP export formats
21
+
2. **Schema Compatibility**: Map existing GenAiSpan structure to Agent Trace schema
22
+
3. **VCS Integration**: Detect and include git/jj revision information
23
+
4. **Model Attribution**: Include model identifiers in trace records
24
+
5. **Backward Compatible**: Keep existing OpenTelemetry export functionality
25
+
26
+
## Proposed Architecture
27
+
28
+
```
29
+
┌─────────────────┐
30
+
│ opencode logs │
31
+
└────────┬────────┘
32
+
│
33
+
▼
34
+
┌──────────────────────┐
35
+
│ LogParser │
36
+
│ - parse_entries() │
37
+
└────────┬─────────────┘
38
+
│
39
+
├── GenAiSpan[] ──────────┐
40
+
│ │
41
+
│ ▼
42
+
│ ┌──────────────────┐
43
+
│ │ OtelExporter │
44
+
│ │ - OTLP format │
45
+
│ └──────────────────┘
46
+
│
47
+
▼
48
+
┌──────────────────────────┐
49
+
│ AgentTraceExporter │
50
+
│ - Agent Trace format │
51
+
└──────────────────────────┘
52
+
```
53
+
54
+
## Implementation Plan
55
+
56
+
### Phase 1: Core Data Structures
57
+
58
+
#### 1.1 Add Agent Trace Schema Types
59
+
60
+
```rust
61
+
// src/agent_trace.rs
62
+
63
+
use serde::{Deserialize, Serialize};
64
+
use uuid::Uuid;
65
+
66
+
#[derive(Debug, Clone, Serialize, Deserialize)]
67
+
pub struct TraceRecord {
68
+
version: String,
69
+
id: String,
70
+
timestamp: String,
71
+
#[serde(skip_serializing_if = "Option::is_none")]
72
+
vcs: Option<VcsInfo>,
73
+
#[serde(skip_serializing_if = "Option::is_none")]
74
+
tool: Option<ToolInfo>,
75
+
files: Vec<FileRecord>,
76
+
#[serde(skip_serializing_if = "Option::is_none")]
77
+
metadata: Option<serde_json::Value>,
78
+
}
79
+
80
+
#[derive(Debug, Clone, Serialize, Deserialize)]
81
+
pub struct VcsInfo {
82
+
r#type: VcsType,
83
+
revision: String,
84
+
}
85
+
86
+
#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
87
+
#[serde(rename_all = "lowercase")]
88
+
pub enum VcsType {
89
+
Git,
90
+
Jj,
91
+
Hg,
92
+
Svn,
93
+
}
94
+
95
+
#[derive(Debug, Clone, Serialize, Deserialize)]
96
+
pub struct ToolInfo {
97
+
name: String,
98
+
version: String,
99
+
}
100
+
101
+
#[derive(Debug, Clone, Serialize, Deserialize)]
102
+
pub struct FileRecord {
103
+
path: String,
104
+
conversations: Vec<ConversationRecord>,
105
+
}
106
+
107
+
#[derive(Debug, Clone, Serialize, Deserialize)]
108
+
pub struct ConversationRecord {
109
+
#[serde(skip_serializing_if = "Option::is_none")]
110
+
url: Option<String>,
111
+
contributor: Contributor,
112
+
ranges: Vec<RangeRecord>,
113
+
#[serde(skip_serializing_if = "Option::is_none")]
114
+
related: Option<Vec<RelatedResource>>,
115
+
}
116
+
117
+
#[derive(Debug, Clone, Serialize, Deserialize)]
118
+
pub struct Contributor {
119
+
r#type: ContributorType,
120
+
#[serde(skip_serializing_if = "Option::is_none")]
121
+
model_id: Option<String>,
122
+
}
123
+
124
+
#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
125
+
#[serde(rename_all = "lowercase")]
126
+
pub enum ContributorType {
127
+
Human,
128
+
Ai,
129
+
Mixed,
130
+
Unknown,
131
+
}
132
+
133
+
#[derive(Debug, Clone, Serialize, Deserialize)]
134
+
pub struct RangeRecord {
135
+
start_line: u32,
136
+
end_line: u32,
137
+
#[serde(skip_serializing_if = "Option::is_none")]
138
+
content_hash: Option<String>,
139
+
#[serde(skip_serializing_if = "Option::is_none")]
140
+
contributor: Option<Contributor>,
141
+
}
142
+
143
+
#[derive(Debug, Clone, Serialize, Deserialize)]
144
+
pub struct RelatedResource {
145
+
r#type: RelatedType,
146
+
url: String,
147
+
}
148
+
149
+
#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
150
+
#[serde(rename_all = "lowercase")]
151
+
pub enum RelatedType {
152
+
Session,
153
+
Prompt,
154
+
Tool,
155
+
}
156
+
157
+
impl TraceRecord {
158
+
pub fn new() -> Self {
159
+
Self {
160
+
version: "0.1.0".to_string(),
161
+
id: Uuid::new_v4().to_string(),
162
+
timestamp: chrono::Utc::now().to_rfc3339(),
163
+
vcs: None,
164
+
tool: Some(ToolInfo {
165
+
name: "exp2span".to_string(),
166
+
version: env!("CARGO_PKG_VERSION").to_string(),
167
+
}),
168
+
files: Vec::new(),
169
+
metadata: None,
170
+
}
171
+
}
172
+
}
173
+
```
174
+
175
+
#### 1.2 Model ID Extraction
176
+
177
+
Add helper to extract model IDs from log headers:
178
+
179
+
```rust
180
+
// src/parser.rs enhancement
181
+
182
+
impl LogMessage {
183
+
pub fn model_id(&self) -> Option<String> {
184
+
if let Some(model) = &self.model {
185
+
self.parse_model_id(model)
186
+
} else {
187
+
None
188
+
}
189
+
}
190
+
191
+
fn parse_model_id(&self, model: &str) -> Option<String> {
192
+
match model {
193
+
m if m.contains("claude") => {
194
+
let version = self.extract_version(m)?;
195
+
Some(format!("anthropic/claude-{}", version))
196
+
}
197
+
m if m.contains("gpt") => {
198
+
let version = self.extract_version(m)?;
199
+
Some(format!("openai/gpt-{}", version))
200
+
}
201
+
_ => None,
202
+
}
203
+
}
204
+
205
+
fn extract_version(&self, model: &str) -> Option<String> {
206
+
let re = regex::Regex::new(r"(claude|gpt)[-_]?([0-9.]+)")?;
207
+
re.captures(model)
208
+
.and_then(|c| c.get(2))
209
+
.map(|m| m.as_str().to_string())
210
+
}
211
+
}
212
+
```
213
+
214
+
### Phase 2: VCS Detection
215
+
216
+
```rust
217
+
// src/vcs.rs
218
+
219
+
use anyhow::Result;
220
+
use std::process::Command;
221
+
222
+
#[derive(Debug, Clone)]
223
+
pub enum VcsSystem {
224
+
Git { revision: String },
225
+
Jj { change_id: String },
226
+
}
227
+
228
+
pub fn detect_vcs() -> Result<Option<VcsSystem>> {
229
+
if PathBuf::from(".jj").exists() {
230
+
let change_id = get_jj_change_id()?;
231
+
Ok(Some(VcsSystem::Jj { change_id }))
232
+
} else if PathBuf::from(".git").exists() {
233
+
let revision = get_git_revision()?;
234
+
Ok(Some(VcsSystem::Git { revision }))
235
+
} else {
236
+
Ok(None)
237
+
}
238
+
}
239
+
240
+
fn get_jj_change_id() -> Result<String> {
241
+
let output = Command::new("jj")
242
+
.args(["log", "--limit", "1", "-T", "change_id"])
243
+
.output()?;
244
+
Ok(String::from_utf8(output.stdout)?.trim().to_string())
245
+
}
246
+
247
+
fn get_git_revision() -> Result<String> {
248
+
let output = Command::new("git")
249
+
.args(["rev-parse", "HEAD"])
250
+
.output()?;
251
+
Ok(String::from_utf8(output.stdout)?.trim().to_string())
252
+
}
253
+
```
254
+
255
+
### Phase 3: Exporter Implementation
256
+
257
+
```typescript
258
+
// src/commands/agent-trace.ts
259
+
260
+
import { Command } from 'commander';
261
+
import { promises as fs } from 'fs';
262
+
import path from 'path';
263
+
264
+
interface TraceRecord {
265
+
version: string;
266
+
id: string;
267
+
timestamp: string;
268
+
vcs?: VcsInfo;
269
+
tool?: ToolInfo;
270
+
files: FileRecord[];
271
+
metadata?: Record<string, any>;
272
+
}
273
+
274
+
interface VcsInfo {
275
+
type: 'git' | 'jj' | 'hg' | 'svn';
276
+
revision: string;
277
+
}
278
+
279
+
interface ToolInfo {
280
+
name: string;
281
+
version: string;
282
+
}
283
+
284
+
interface FileRecord {
285
+
path: string;
286
+
conversations: ConversationRecord[];
287
+
}
288
+
289
+
interface ConversationRecord {
290
+
url?: string;
291
+
contributor: Contributor;
292
+
ranges: RangeRecord[];
293
+
related?: RelatedResource[];
294
+
}
295
+
296
+
interface Contributor {
297
+
type: 'human' | 'ai' | 'mixed' | 'unknown';
298
+
model_id?: string;
299
+
}
300
+
301
+
interface RangeRecord {
302
+
start_line: number;
303
+
end_line: number;
304
+
content_hash?: string;
305
+
contributor?: Contributor;
306
+
}
307
+
308
+
interface RelatedResource {
309
+
type: 'session' | 'prompt' | 'tool';
310
+
url: string;
311
+
}
312
+
313
+
interface GenAiSpan {
314
+
session_id: string;
315
+
timestamp: string;
316
+
model?: string;
317
+
agent?: string;
318
+
span_type: 'chat' | 'thinking' | 'tool_call';
319
+
attributes: Record<string, any>;
320
+
role: 'user' | 'assistant';
321
+
}
322
+
323
+
export interface AgentTraceOptions {
324
+
file: string;
325
+
output?: string;
326
+
includeVcs?: boolean;
327
+
includeModel?: boolean;
328
+
lineLength?: number;
329
+
}
330
+
331
+
export async function execute(options: AgentTraceOptions): Promise<void> {
332
+
const {
333
+
file,
334
+
output = '.agent-trace.json',
335
+
includeVcs = true,
336
+
includeModel = true,
337
+
lineLength = 100,
338
+
} = options;
339
+
340
+
const trace: TraceRecord = {
341
+
version: '0.1.0',
342
+
id: crypto.randomUUID(),
343
+
timestamp: new Date().toISOString(),
344
+
vcs: includeVcs ? await detectVcs() : undefined,
345
+
tool: {
346
+
name: 'exp2span',
347
+
version: process.env.npm_package_version || '0.1.0',
348
+
},
349
+
files: [],
350
+
metadata: {
351
+
config: { lineLength },
352
+
},
353
+
};
354
+
355
+
const spans = await parseLog(file);
356
+
trace.files = groupByFile(spans, lineLength);
357
+
358
+
await fs.writeFile(output, JSON.stringify(trace, null, 2));
359
+
console.log(`Agent Trace written to: ${output}`);
360
+
}
361
+
362
+
async function detectVcs(): Promise<VcsInfo | undefined> {
363
+
try {
364
+
const gitHead = await fs.readFile('.git/HEAD', 'utf-8');
365
+
const refPath = gitHead.trim();
366
+
const refContent = await fs.readFile(`.git/${refPath}`, 'utf-8');
367
+
const revision = refContent.trim();
368
+
369
+
return {
370
+
type: 'git',
371
+
revision,
372
+
};
373
+
} catch {
374
+
try {
375
+
const output = await exec('jj log --limit 1 -T change_id');
376
+
const changeId = output.stdout.trim();
377
+
return {
378
+
type: 'jj',
379
+
revision: changeId,
380
+
};
381
+
} catch {
382
+
return undefined;
383
+
}
384
+
}
385
+
}
386
+
387
+
function parseModelId(model?: string): string | undefined {
388
+
if (!model) return undefined;
389
+
390
+
if (model.includes('claude')) {
391
+
const version = extractVersion(model);
392
+
return `anthropic/claude-${version}`;
393
+
}
394
+
if (model.includes('gpt')) {
395
+
const version = extractVersion(model);
396
+
return `openai/gpt-${version}`;
397
+
}
398
+
return undefined;
399
+
}
400
+
401
+
function extractVersion(model: string): string | undefined {
402
+
const match = model.match(/(claude|gpt)[-_]?([0-9.]+)/);
403
+
return match?.[2];
404
+
}
405
+
406
+
function groupByFile(spans: GenAiSpan[], lineLength: number): FileRecord[] {
407
+
const files = new Map<string, FileRecord>();
408
+
409
+
for (const span of spans) {
410
+
const modelId = parseModelId(span.model);
411
+
412
+
const contributor: Contributor = {
413
+
type: span.role === 'user' ? 'human' : 'ai',
414
+
model_id: includeModel ? modelId : undefined,
415
+
};
416
+
417
+
const contentLength = estimateContentLength(span);
418
+
const estimatedLines = Math.ceil(contentLength / lineLength);
419
+
420
+
const conversation: ConversationRecord = {
421
+
url: span.session_id,
422
+
contributor,
423
+
ranges: [{
424
+
start_line: 1,
425
+
end_line: estimatedLines,
426
+
}],
427
+
};
428
+
429
+
const filePath = span.attributes['gen_ai.file.path'] || 'unknown';
430
+
let file = files.get(filePath);
431
+
if (!file) {
432
+
file = { path: filePath, conversations: [] };
433
+
files.set(filePath, file);
434
+
}
435
+
file.conversations.push(conversation);
436
+
}
437
+
438
+
return Array.from(files.values());
439
+
}
440
+
441
+
function estimateContentLength(span: GenAiSpan): number {
442
+
switch (span.span_type) {
443
+
case 'tool_call':
444
+
return JSON.stringify(span.attributes['gen_ai.tool.call.arguments'] || {}).length;
445
+
case 'chat':
446
+
case 'thinking':
447
+
const inputLen = JSON.stringify(span.attributes['gen_ai.input.messages'] || []).length;
448
+
const outputLen = JSON.stringify(span.attributes['gen_ai.output.messages'] || []).length;
449
+
return inputLen + outputLen;
450
+
default:
451
+
return 100;
452
+
}
453
+
}
454
+
```
455
+
456
+
```bash
457
+
# Add to tsconfig.json for TypeScript support
458
+
{
459
+
"compilerOptions": {
460
+
"outDir": "./dist",
461
+
"rootDir": "./src",
462
+
"module": "ESNext",
463
+
"target": "ES2022",
464
+
"moduleResolution": "bundler"
465
+
}
466
+
}
467
+
```
468
+
469
+
### Phase 4: CLI Integration
470
+
471
+
#### 4.1 New Output Format
472
+
473
+
```rust
474
+
// src/cli.rs
475
+
476
+
#[derive(ValueEnum, Clone, Copy, Debug, PartialEq)]
477
+
pub enum OutputFormat {
478
+
Otlp,
479
+
Json,
480
+
JsonLines,
481
+
Yaml,
482
+
Table,
483
+
AgentTrace, // NEW
484
+
}
485
+
```
486
+
487
+
#### 4.2 New Subcommand
488
+
489
+
```rust
490
+
// src/cli.rs
491
+
492
+
#[derive(Subcommand)]
493
+
pub enum Commands {
494
+
Export(ExportArgs),
495
+
Validate(ValidateArgs),
496
+
Info(InfoArgs),
497
+
Completion(CompletionArgs),
498
+
AgentTrace(AgentTraceArgs), // NEW
499
+
}
500
+
501
+
#[derive(Parser, Debug)]
502
+
pub struct AgentTraceArgs {
503
+
/// Path to log file
504
+
#[arg(value_name = "FILE")]
505
+
pub file: PathBuf,
506
+
507
+
/// Output file for Agent Trace JSON
508
+
#[arg(short, long, default_value = ".agent-trace.json")]
509
+
pub output: PathBuf,
510
+
511
+
/// Include VCS information in trace
512
+
#[arg(short, long, default_value_t = true)]
513
+
pub include_vcs: bool,
514
+
515
+
/// Include model ID in contributor info
516
+
#[arg(short, long, default_value_t = true)]
517
+
pub include_model: bool,
518
+
519
+
/// Character count per line for estimation (default: 100)
520
+
#[arg(short, long, default_value_t = 100usize)]
521
+
pub line_length: usize,
522
+
}
523
+
```
524
+
525
+
#### 4.3 Commands Module
526
+
527
+
```rust
528
+
// src/commands/mod.rs
529
+
530
+
pub mod agent_trace; // NEW
531
+
532
+
pub use agent_trace::execute as agent_trace_execute;
533
+
534
+
pub async fn execute(cmd: Commands, output: OutputFormat) -> Result<()> {
535
+
match cmd {
536
+
Commands::Export(args) => export_execute(args, output).await,
537
+
Commands::Validate(args) => validate_execute(args),
538
+
Commands::Info(args) => info_execute(args),
539
+
Commands::Completion(args) => completion_execute(args),
540
+
Commands::AgentTrace(args) => agent_trace_execute(args), // NEW
541
+
}
542
+
}
543
+
```
544
+
545
+
### Phase 5: Config Support
546
+
547
+
```toml
548
+
# .exp2span.toml
549
+
550
+
[agent_trace]
551
+
# Include VCS information in traces
552
+
include_vcs = true
553
+
554
+
# Include model IDs in contributor info
555
+
include_model = true
556
+
557
+
# Default output directory
558
+
output_dir = ".agent-trace"
559
+
560
+
# Content hash algorithm (murmur3, sha256, none)
561
+
hash_algorithm = "murmur3"
562
+
563
+
# Character count per line for estimation (default: 100)
564
+
line_length = 100
565
+
```
566
+
567
+
```rust
568
+
// src/config.rs
569
+
570
+
#[derive(Debug, Clone, Deserialize)]
571
+
#[serde(default)]
572
+
pub struct AgentTraceConfig {
573
+
pub include_vcs: bool,
574
+
pub include_model: bool,
575
+
pub output_dir: PathBuf,
576
+
pub hash_algorithm: String,
577
+
578
+
/// Character count per line for estimation (default: 100)
579
+
pub line_length: usize,
580
+
}
581
+
582
+
impl Default for AgentTraceConfig {
583
+
fn default() -> Self {
584
+
Self {
585
+
include_vcs: true,
586
+
include_model: true,
587
+
output_dir: PathBuf::from(".agent-trace"),
588
+
hash_algorithm: "murmur3".to_string(),
589
+
line_length: 100,
590
+
}
591
+
}
592
+
}
593
+
```
594
+
595
+
## Data Mapping
596
+
597
+
### GenAiSpan to TraceRecord
598
+
599
+
| GenAiSpan Field | TraceRecord Field | Notes |
600
+
|-----------------|------------------|--------|
601
+
| `session_id` | `conversation.url` | Construct from session ID |
602
+
| `timestamp` | `conversation.url` or `timestamp` | Use session timestamp |
603
+
| `model` | `contributor.model_id` | Parse model ID |
604
+
| `agent` | `tool.name` | Use agent name |
605
+
| `tool.name` | N/A | Tool is what agent executes, not agent itself |
606
+
| `duration_ms` | N/A | Agent Trace uses line ranges, not durations |
607
+
| `span_type` | `contributor.type` | AI-generated = `ai`, User chats = `human` |
608
+
| `attributes` | `metadata` | Copy arbitrary attributes |
609
+
610
+
### Tool vs Agent Mapping Clarification
611
+
612
+
The `tool.name` field in opencode logs typically refers to specific tools the agent executes (e.g., `EditFile`, `RunShell`, `ReadFile`, etc.), not the agent itself. The agent name should map to `tool.name` in Agent Trace, while the specific tool names used during the conversation could optionally be captured in `related` resources or `metadata`.
613
+
614
+
### Line Estimation
615
+
616
+
Since opencode logs don't have explicit line numbers, we estimate based on configurable line length:
617
+
618
+
```rust
619
+
// src/parser.rs enhancement
620
+
621
+
impl GenAiSpan {
622
+
/// Estimate number of lines based on content length and configured line length
623
+
pub fn estimated_lines(&self, line_length: usize) -> u32 {
624
+
let content_len = match self.span_type {
625
+
SpanType::ToolCall => {
626
+
self.attributes.get("gen_ai.tool.call.arguments")
627
+
.and_then(|v| v.as_str())
628
+
.map(|s| s.len())
629
+
.unwrap_or(100)
630
+
}
631
+
SpanType::Chat | SpanType::Thinking => {
632
+
let input = self.attributes.get("gen_ai.input.messages")
633
+
.and_then(|v| v.as_str())
634
+
.map(|s| s.len())
635
+
.unwrap_or(0);
636
+
let output = self.attributes.get("gen_ai.output.messages")
637
+
.and_then(|v| v.as_str())
638
+
.map(|s| s.len())
639
+
.unwrap_or(0);
640
+
(input + output) as usize
641
+
}
642
+
};
643
+
644
+
((content_len as f64) / (line_length as f64)).ceil() as u32
645
+
}
646
+
647
+
pub fn file_path(&self) -> String {
648
+
self.attributes.get("gen_ai.file.path")
649
+
.and_then(|v| v.as_str())
650
+
.unwrap_or("unknown")
651
+
.to_string()
652
+
}
653
+
}
654
+
```
655
+
656
+
### Configurable Line Length
657
+
658
+
Add to config:
659
+
660
+
```rust
661
+
// src/config.rs
662
+
663
+
#[derive(Debug, Clone, Deserialize)]
664
+
#[serde(default)]
665
+
pub struct AgentTraceConfig {
666
+
pub include_vcs: bool,
667
+
pub include_model: bool,
668
+
pub output_dir: PathBuf,
669
+
pub hash_algorithm: String,
670
+
671
+
/// Character count to use when estimating line numbers
672
+
/// Default: 100 characters per line
673
+
pub line_length: usize,
674
+
}
675
+
676
+
impl Default for AgentTraceConfig {
677
+
fn default() -> Self {
678
+
Self {
679
+
include_vcs: true,
680
+
include_model: true,
681
+
output_dir: PathBuf::from(".agent-trace"),
682
+
hash_algorithm: "murmur3".to_string(),
683
+
line_length: 100,
684
+
}
685
+
}
686
+
}
687
+
```
688
+
689
+
## Dependencies
690
+
691
+
Add to package.json for TypeScript:
692
+
693
+
```json
694
+
{
695
+
"dependencies": {
696
+
"commander": "^12.0.0",
697
+
"types": "^0.12.0",
698
+
"@types/node": "^20.0.0"
699
+
},
700
+
"devDependencies": {
701
+
"@types/node": "^20.0.0",
702
+
"typescript": "^5.0.0",
703
+
"tsx": "^4.0.0"
704
+
},
705
+
"scripts": {
706
+
"build": "tsc",
707
+
"agent-trace": "tsx src/commands/agent-trace.ts"
708
+
}
709
+
}
710
+
```
711
+
712
+
## Migration Path
713
+
714
+
### Step 1: Add TypeScript Agent Trace Export (Week 1)
715
+
- Set up TypeScript project structure
716
+
- Implement core data structures (interfaces)
717
+
- Add VCS detection (git/jj)
718
+
- Implement basic agent-trace.ts exporter
719
+
- Add CLI integration with commander
720
+
721
+
### Step 2: Enhance Line Tracking (Week 2)
722
+
- Add configurable line length support
723
+
- Implement content length estimation
724
+
- Support custom file paths in attributes
725
+
- Add tests for line estimation
726
+
727
+
### Step 3: Integration & Testing (Week 3)
728
+
- Add config support for agent-trace options
729
+
- Write tests for VCS detection
730
+
- Update documentation with examples
731
+
- Create example traces
732
+
- Test with real opencode log files
733
+
734
+
### Step 4: Polish (Week 4)
735
+
- Error handling for file I/O
736
+
- Performance optimization for large logs
737
+
- CI/CD updates for TypeScript build
738
+
- User feedback integration
739
+
- Validate against Agent Trace JSON Schema
740
+
741
+
## Open Questions
742
+
743
+
1. **File Association**: opencode logs don't explicitly specify which files were modified. Should we:
744
+
- Require file paths in log attributes?
745
+
- Infer from git diff for the session?
746
+
- Use a default placeholder?
747
+
748
+
2. **Line Numbers**: Should we attempt to match log content to actual code files to find exact line ranges, or use estimates based on content length?
749
+
750
+
3. **Human Contributions**: How should we handle human-authored code in the same session? Mixed contributor type, or separate files?
751
+
752
+
4. **Output Format**: Should Agent Trace be:
753
+
- A separate output format (like JSON/YAML)?
754
+
- Automatically written alongside OTLP export?
755
+
- An opt-in mode?
756
+
757
+
## Acceptance Criteria
758
+
759
+
- [ ] Export command generates valid Agent Trace JSON
760
+
- [ ] VCS detection works for git and jj
761
+
- [ ] Model IDs are correctly parsed and formatted
762
+
- [ ] Trace records pass JSON Schema validation
763
+
- [ ] CLI `exp2span agent-trace <file>` works
764
+
- [ ] Config file support for Agent Trace options
765
+
- [ ] Configurable line length estimation (default 100 chars)
766
+
- [ ] Documentation updated with Agent Trace examples
767
+
- [ ] Tests added for Agent Trace generation
768
+
- [ ] Backward compatible with existing OTLP export
769
+
- [ ] TypeScript build process working with tsc
770
+
771
+
## References
772
+
773
+
- [Agent Trace Specification](https://agent-trace.dev/)
774
+
- [Agent Trace GitHub](https://github.com/cursor/agent-trace)
775
+
- [Agent Trace Reference Implementation](https://github.com/cursor/agent-trace/tree/main/reference)
776
+
- [models.dev Convention](https://models.dev/)
777
+
- [OpenCode MCP Spec](https://github.com/opencode-co/mcp-spec)