agent-trajectories 0.1.0

package/docs/architecture/web-viewer.md

@@ -0,0 +1,213 @@
+# Web Viewer Architecture
+
+## Overview
+
+A lightweight local web interface for humans to browse and read trajectories in a Notion-like format.
+
+## Design Goals
+
+1. **Zero external dependencies** - No cloud services, runs entirely local
+2. **Instant startup** - `traj view` opens browser immediately
+3. **No build step** - Works without webpack/vite in dev
+4. **Offline-first** - All data from local `.trajectories/`
+
+## Architecture Options
+
+### Option A: Static HTML Export (Recommended for v1)
+
+Generate a self-contained HTML file with embedded data:
+
+```
+traj view                    # Opens generated HTML in browser
+traj view --serve            # Start live server with hot reload
+traj view --export site/     # Generate static site
+```
+
+**Pros:**
+- No server needed for basic viewing
+- Can be committed to repo for sharing
+- Works offline, shareable via email
+
+**Cons:**
+- No live updates without regeneration
+
+### Option B: Local Dev Server
+
+Run a lightweight HTTP server:
+
+```
+traj serve                   # Start server at localhost:3847
+```
+
+**Stack:**
+- Node HTTP server (built-in, no Express needed)
+- Preact for UI (3KB, no build step with htm)
+- CSS: Simple stylesheet, no framework
+
+**Pros:**
+- Live updates as trajectories change
+- Search and filter in UI
+
+**Cons:**
+- Requires running server
+
+### Option C: Hybrid (Recommended)
+
+Combine both: static HTML for sharing, local server for active use.
+
+## UI Components
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  🛤️ Trajectories                              [Search...] [⚙️]  │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  SIDEBAR                    │  MAIN VIEW                        │
+│  ─────────                  │  ─────────                        │
+│                             │                                   │
+│  ▸ Active (1)               │  📋 Implement User Auth           │
+│    └─ traj_abc123           │  ━━━━━━━━━━━━━━━━━━━━━━━━━        │
+│                             │                                   │
+│  ▸ This Week (5)            │  Status: ● Active                 │
+│                             │  Started: 2h ago                  │
+│  ▸ Completed (23)           │  Agent: Claude                    │
+│                             │                                   │
+│  ▸ Abandoned (2)            │  ▾ Summary                        │
+│                             │    JWT auth with refresh tokens   │
+│  ──────────────             │                                   │
+│  📁 Workspace               │  ▾ Key Decisions (2)              │
+│    ├─ Decisions             │    ├─ JWT over sessions           │
+│    ├─ Patterns              │    └─ Bcrypt for passwords        │
+│    └─ Knowledge             │                                   │
+│                             │  ▾ Timeline                       │
+│                             │    10:00 Started                  │
+│                             │    10:15 Research phase           │
+│                             │    10:30 Decision: JWT            │
+│                             │    11:00 Implementation           │
+│                             │                                   │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Implementation Plan
+
+### Phase 1: Static HTML Generator
+- Generate single HTML file with all trajectory data
+- Embedded CSS (light/dark mode)
+- Collapsible sections for chapters, decisions
+- `traj view <id>` opens single trajectory
+- `traj view --all` generates index + all trajectories
+
+### Phase 2: Local Server
+- Add `traj serve` command
+- WebSocket for live updates
+- Search across all trajectories
+- Filtering by status, date, agent
+
+### Phase 3: Workspace Integration
+- Sidebar shows workspace knowledge
+- Link decisions to source trajectories
+- Pattern library view
+- "Related trajectories" for context
+
+## File Structure
+
+```
+src/
+├── web/
+│   ├── server.ts           # HTTP server
+│   ├── templates/
+│   │   ├── index.html      # Main shell
+│   │   ├── trajectory.html # Single trajectory view
+│   │   └── styles.css      # Embedded styles
+│   ├── generator.ts        # Static HTML generator
+│   └── components/         # Preact components (Phase 2)
+│       ├── Sidebar.tsx
+│       ├── Timeline.tsx
+│       └── DecisionCard.tsx
+```
+
+## CLI Integration
+
+```bash
+# View commands
+traj view                  # Open active trajectory in browser
+traj view <id>             # Open specific trajectory
+traj view --all            # Open index of all trajectories
+
+# Server commands
+traj serve                 # Start local server
+traj serve --port 8080     # Custom port
+
+# Export for sharing
+traj export <id> --format html --output trajectory.html
+traj export --all --format html --output ./docs/trajectories/
+```
+
+## Workspace Layer
+
+The workspace extracts durable knowledge from trajectories:
+
+```
+.agent-workspace/
+├── decisions/
+│   ├── index.json              # All decisions with links
+│   └── auth-approach.md        # Individual decision doc
+├── patterns/
+│   ├── index.json
+│   └── api-endpoint.md         # Reusable pattern
+├── knowledge/
+│   ├── architecture.md         # Codebase knowledge
+│   └── conventions.md          # Team conventions
+└── config.json                 # Workspace settings
+```
+
+### Decision Extraction
+
+When a trajectory completes, decisions can be promoted to workspace:
+
+```bash
+traj workspace promote-decision <trajectory-id> <decision-index>
+# or interactively after completion
+```
+
+### Query Interface
+
+Agents query the workspace:
+
+```typescript
+interface WorkspaceQuery {
+  type: 'decision' | 'pattern' | 'trajectory' | 'any';
+  query: string;
+  context?: string;  // Current task context
+  limit?: number;
+}
+
+// Example: Agent asks about auth
+workspace.query({
+  type: 'any',
+  query: 'authentication',
+  context: 'implementing login flow'
+});
+
+// Returns:
+// - Decision: "Use JWT for auth"
+// - Pattern: "Auth middleware template"
+// - Trajectory: traj_abc123 (implemented auth before)
+```
+
+## Technology Choices
+
+| Component | Choice | Rationale |
+|-----------|--------|-----------|
+| Server | Node http | Zero deps, built-in |
+| UI (v1) | Vanilla JS | No build step |
+| UI (v2) | Preact + htm | 3KB, no build needed |
+| CSS | Custom | Simple, themed |
+| Icons | Unicode emoji | No icon deps |
+
+## Questions to Resolve
+
+1. **Workspace location**: `.agent-workspace/` vs inside `.trajectories/workspace/`?
+2. **Knowledge format**: Markdown files vs JSON?
+3. **Pattern templates**: How to make patterns executable/reusable?
+4. **Multi-repo**: How does workspace work across repos?

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "agent-trajectories",
+  "version": "0.1.0",
+  "description": "Capture the complete train of thought of agent work as first-class artifacts",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "trail": "dist/cli/index.js"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "format": "biome format --write .",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "agent",
+    "trajectory",
+    "ai",
+    "claude",
+    "llm",
+    "debugging",
+    "tracing"
+  ],
+  "author": "",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.7.0",
+    "commander": "^12.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.8.0",
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^2.0.0"
+  }
+}

package/src/cli/commands/abandon.ts

@@ -0,0 +1,32 @@
+/**
+ * trail abandon command
+ */
+
+import type { Command } from "commander";
+import { abandonTrajectory } from "../../core/trajectory.js";
+import { FileStorage } from "../../storage/file.js";
+
+export function registerAbandonCommand(program: Command): void {
+  program
+    .command("abandon")
+    .description("Abandon the active trajectory")
+    .option("-r, --reason <text>", "Reason for abandonment")
+    .action(async (options) => {
+      const storage = new FileStorage();
+      await storage.initialize();
+
+      const active = await storage.getActive();
+      if (!active) {
+        console.error("Error: No active trajectory");
+        throw new Error("No active trajectory");
+      }
+
+      const abandoned = abandonTrajectory(active, options.reason);
+      await storage.save(abandoned);
+
+      console.log(`✓ Trajectory abandoned: ${abandoned.id}`);
+      if (options.reason) {
+        console.log(`  Reason: ${options.reason}`);
+      }
+    });
+}

package/src/cli/commands/complete.ts

@@ -0,0 +1,51 @@
+/**
+ * trail complete command
+ */
+
+import type { Command } from "commander";
+import { completeTrajectory } from "../../core/trajectory.js";
+import { FileStorage } from "../../storage/file.js";
+
+export function registerCompleteCommand(program: Command): void {
+  program
+    .command("complete")
+    .description("Complete the active trajectory with retrospective")
+    .option("--summary <text>", "Summary of what was accomplished")
+    .option("--approach <text>", "How the work was approached")
+    .option("--confidence <number>", "Confidence level 0-1", parseFloat)
+    .action(async (options) => {
+      const storage = new FileStorage();
+      await storage.initialize();
+
+      const active = await storage.getActive();
+      if (!active) {
+        console.error("Error: No active trajectory");
+        console.error("Start one with: trail start \"Task description\"");
+        throw new Error("No active trajectory");
+      }
+
+      // Require summary and confidence
+      if (!options.summary) {
+        console.error("Error: --summary is required");
+        throw new Error("Summary required");
+      }
+
+      const confidence = options.confidence ?? 0.8;
+      if (confidence < 0 || confidence > 1) {
+        console.error("Error: --confidence must be between 0 and 1");
+        throw new Error("Invalid confidence");
+      }
+
+      const completed = completeTrajectory(active, {
+        summary: options.summary,
+        approach: options.approach || "Standard approach",
+        confidence,
+      });
+
+      await storage.save(completed);
+
+      console.log(`✓ Trajectory completed: ${completed.id}`);
+      console.log(`  Summary: ${options.summary}`);
+      console.log(`  Confidence: ${Math.round(confidence * 100)}%`);
+    });
+}

package/src/cli/commands/decision.ts

@@ -0,0 +1,49 @@
+/**
+ * trail decision command
+ */
+
+import type { Command } from "commander";
+import { addDecision } from "../../core/trajectory.js";
+import { FileStorage } from "../../storage/file.js";
+
+export function registerDecisionCommand(program: Command): void {
+  program
+    .command("decision <choice>")
+    .description("Record a decision")
+    .option("-r, --reasoning <text>", "Why this choice was made (optional for minor decisions)")
+    .option("-a, --alternatives <items>", "Comma-separated alternatives considered")
+    .action(async (choice: string, options) => {
+      const storage = new FileStorage();
+      await storage.initialize();
+
+      const active = await storage.getActive();
+      if (!active) {
+        console.error("Error: No active trajectory");
+        console.error("Start one with: trail start \"Task description\"");
+        throw new Error("No active trajectory");
+      }
+
+      const alternatives = options.alternatives
+        ? options.alternatives.split(",").map((s: string) => s.trim())
+        : [];
+
+      const reasoning = options.reasoning || "";
+
+      const updated = addDecision(active, {
+        question: choice,
+        chosen: choice,
+        alternatives,
+        reasoning,
+      });
+
+      await storage.save(updated);
+
+      console.log(`✓ Decision recorded: ${choice}`);
+      if (reasoning) {
+        console.log(`  Reasoning: ${reasoning}`);
+      }
+      if (alternatives.length > 0) {
+        console.log(`  Alternatives: ${alternatives.join(", ")}`);
+      }
+    });
+}

package/src/cli/commands/export.ts

@@ -0,0 +1,100 @@
+/**
+ * trail export command
+ */
+
+import type { Command } from "commander";
+import { writeFile, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { exec } from "node:child_process";
+import { FileStorage } from "../../storage/file.js";
+import { exportToMarkdown } from "../../export/markdown.js";
+import { exportToJSON } from "../../export/json.js";
+import { exportToTimeline } from "../../export/timeline.js";
+import { generateTrajectoryHtml } from "../../web/generator.js";
+
+export function registerExportCommand(program: Command): void {
+  program
+    .command("export [id]")
+    .description("Export a trajectory")
+    .option("-f, --format <format>", "Export format (md, json, timeline, html)", "md")
+    .option("-o, --output <path>", "Output file path")
+    .option("--open", "Open in browser (html format only)")
+    .action(async (id: string | undefined, options) => {
+      const storage = new FileStorage();
+      await storage.initialize();
+
+      // If no ID provided, use active trajectory
+      let trajectory;
+      if (id) {
+        trajectory = await storage.get(id);
+        if (!trajectory) {
+          console.error(`Error: Trajectory not found: ${id}`);
+          throw new Error("Trajectory not found");
+        }
+      } else {
+        trajectory = await storage.getActive();
+        if (!trajectory) {
+          console.error("Error: No active trajectory and no ID provided");
+          console.error("Usage: trail export <id> or trail export (with active trajectory)");
+          throw new Error("No trajectory specified");
+        }
+      }
+
+      let output: string;
+
+      switch (options.format) {
+        case "json":
+          output = exportToJSON(trajectory);
+          break;
+        case "timeline":
+          output = exportToTimeline(trajectory);
+          break;
+        case "html":
+          output = generateTrajectoryHtml(trajectory);
+          break;
+        case "md":
+        case "markdown":
+        default:
+          output = exportToMarkdown(trajectory);
+          break;
+      }
+
+      if (options.output) {
+        await writeFile(options.output, output, "utf-8");
+        console.log(`✓ Exported to ${options.output}`);
+
+        if (options.open && options.format === "html") {
+          openInBrowser(options.output);
+        }
+      } else if (options.open && options.format === "html") {
+        // Write to temp location and open
+        const outputDir = join(process.cwd(), ".trajectories", "html");
+        await mkdir(outputDir, { recursive: true });
+        const filePath = join(outputDir, `${trajectory.id}.html`);
+        await writeFile(filePath, output, "utf-8");
+        console.log(`✓ Generated: ${filePath}`);
+        openInBrowser(filePath);
+      } else {
+        console.log(output);
+      }
+    });
+}
+
+function openInBrowser(path: string): void {
+  const platform = process.platform;
+  let command: string;
+
+  if (platform === "darwin") {
+    command = `open "${path}"`;
+  } else if (platform === "win32") {
+    command = `start "" "${path}"`;
+  } else {
+    command = `xdg-open "${path}"`;
+  }
+
+  exec(command, (error) => {
+    if (error) {
+      console.log(`Open manually: file://${path}`);
+    }
+  });
+}

package/src/cli/commands/index.ts

@@ -0,0 +1,39 @@
+/**
+ * CLI Command Registration
+ *
+ * Registers all commands with the program.
+ *
+ * Core commands (8 total):
+ * - start: Begin tracking a new task
+ * - status: Show current trajectory state
+ * - decision: Record a decision point
+ * - complete: Finish with retrospective
+ * - abandon: Stop without completing
+ * - list: Browse trajectories (with --search)
+ * - show: View trajectory details
+ * - export: Output in various formats (with --open)
+ */
+
+import type { Command } from "commander";
+import { registerStartCommand } from "./start.js";
+import { registerStatusCommand } from "./status.js";
+import { registerCompleteCommand } from "./complete.js";
+import { registerAbandonCommand } from "./abandon.js";
+import { registerDecisionCommand } from "./decision.js";
+import { registerListCommand } from "./list.js";
+import { registerShowCommand } from "./show.js";
+import { registerExportCommand } from "./export.js";
+
+/**
+ * Register all CLI commands
+ */
+export function registerCommands(program: Command): void {
+  registerStartCommand(program);
+  registerStatusCommand(program);
+  registerCompleteCommand(program);
+  registerAbandonCommand(program);
+  registerDecisionCommand(program);
+  registerListCommand(program);
+  registerShowCommand(program);
+  registerExportCommand(program);
+}

package/src/cli/commands/list.ts

@@ -0,0 +1,90 @@
+/**
+ * trail list command
+ */
+
+import type { Command } from "commander";
+import { FileStorage } from "../../storage/file.js";
+import type { TrajectoryStatus } from "../../core/types.js";
+
+export function registerListCommand(program: Command): void {
+  program
+    .command("list")
+    .description("List and search trajectories")
+    .option("-s, --status <status>", "Filter by status (active, completed, abandoned)")
+    .option("-l, --limit <number>", "Limit results", parseInt)
+    .option("--search <query>", "Search trajectories by title or content")
+    .action(async (options) => {
+      const storage = new FileStorage();
+      await storage.initialize();
+
+      let trajectories = await storage.list({
+        status: options.status as TrajectoryStatus | undefined,
+        limit: options.search ? undefined : options.limit, // Apply limit after search
+      });
+
+      // Apply search filter if provided
+      if (options.search) {
+        const query = options.search.toLowerCase();
+        trajectories = trajectories.filter((traj) => {
+          // Search in title
+          if (traj.title.toLowerCase().includes(query)) return true;
+          // Search in ID
+          if (traj.id.toLowerCase().includes(query)) return true;
+          return false;
+        });
+
+        // Apply limit after search
+        if (options.limit) {
+          trajectories = trajectories.slice(0, options.limit);
+        }
+      }
+
+      if (trajectories.length === 0) {
+        if (options.search) {
+          console.log(`No trajectories found matching "${options.search}"`);
+        } else {
+          console.log("No trajectories found");
+        }
+        return;
+      }
+
+      const searchNote = options.search ? ` matching "${options.search}"` : "";
+      console.log(`Found ${trajectories.length} trajectories${searchNote}:\n`);
+
+      for (const traj of trajectories) {
+        const statusIcon = getStatusIcon(traj.status);
+        const confidence = traj.confidence
+          ? ` (${Math.round(traj.confidence * 100)}%)`
+          : "";
+
+        console.log(`${statusIcon} ${traj.id}`);
+        console.log(`   ${traj.title}${confidence}`);
+        console.log(`   Started: ${formatDate(traj.startedAt)}`);
+        if (traj.completedAt) {
+          console.log(`   Completed: ${formatDate(traj.completedAt)}`);
+        }
+        console.log("");
+      }
+    });
+}
+
+function getStatusIcon(status: string): string {
+  switch (status) {
+    case "active":
+      return "🔄";
+    case "completed":
+      return "✅";
+    case "abandoned":
+      return "❌";
+    default:
+      return "•";
+  }
+}
+
+function formatDate(isoString: string): string {
+  return new Date(isoString).toLocaleDateString("en-US", {
+    month: "short",
+    day: "numeric",
+    year: "numeric",
+  });
+}