@raquezha/notrace 0.0.5 → 0.0.6

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @raquezha/notrace
 
+## 0.0.6
+
+### Patch Changes
+
+- d349d36: Refresh the notrace UI and sample session rendering separately from the antigravity billing fix.
+- 51fda83: fix: preserve assistant toolCall blocks in noheadroom compression and expose notrace failure metadata
+- 7afa746: Package updates for antigravity, norpiv, and notrace.
+
 ## 0.0.5
 
 ### Patch Changes

package/README.md

@@ -1,101 +1,148 @@
+<p align="center">
+  <img src="./assets/notrace-logo.svg" alt="notrace logo" width="240" />
+</p>
+
 # notrace
 
-Phase 0 / POC local-first trace capture for the Pi Coding Agent. It captures execution traces for workflow debugging — LLM calls, tool executions, token usage, costs — and writes both an interactive HTML report and a machine-readable `notrace.json` run record to your active task workspace at session end.
+**Traces in, lessons out.**
 
-> **Security warning:** notrace is local-first and now redacts common secrets by default, escapes report rendering, blocks network access in generated reports, and writes private report files. Reports can still contain sensitive prompts, tool payloads, outputs, and local paths. Do not publish generated reports.
+`notrace` is a local-first retrospective engine for the Pi Coding Agent.
+It captures session evidence, writes a versioned `notrace.json` run record, renders a human-readable HTML report, and supports review/compare flows for workflow R&D.
 
-## Boundary with RPIV
+## What notrace owns
 
-The relationship is intentionally optional both ways:
+When enabled, `notrace` is the durable retrospective layer for a session.
+It aggregates:
+- core Pi session telemetry
+- workflow/task context
+- optional dynamic extension telemetry
 
-- **notrace without RPIV**: should work; notrace-owned artifacts belong under `.notrace/`
-- **RPIV without notrace**: should work; `WORK.md` remains the source of truth without any notrace dependency
-- **together**: RPIV `WORK.md [LOG]` may reference notrace artifacts, but `.workflow/` should not own them
+Today, Pi is the first harness adapter.
+The canonical run schema is designed so other harness adapters can be added later, but multi-harness support is not implemented in this package yet.
 
-Neither package should require the other to function.
+## What notrace does not own
 
-## Features
+`notrace` is **not**:
+- the live Pi footer
+- the Pi resume/session-switch UX
+- a scraper of terminal status strings
 
-- **Session timeline**: Every turn, tool call, and LLM completion rendered as an expandable card
-- **Metrics dashboard**: Total tokens, input/output split, cache reads, cost (USD), duration
-- **Machine-readable run record**: Normalized `notrace.json` sidecar for future retrospective/compare flows
-- **Clickable `file://` links**: Artifact paths printed to console at session end for instant browser access
-- **Workdir aware**: notrace-owned artifacts are planned to live under `.notrace/` for the root execution directory
-- **RPIV attachment**: When a task has a `WORK.md`, notrace appends artifact/review references into `[LOG]`
-- **HTML report**: Self-contained/offline report with a restrictive CSP and no remote font/network loads
-- **Safer defaults**: Secret-key/value redaction, bounded payload sizes, metadata-only mode, private file permissions, and `.workflow`-confined artifact writes
+Live footer output, resume hints, and extension footer badges may appear near `notrace` output during shutdown, but they are separate producers.
 
-## Output
+## Retrospective spine
 
+1. **Capture evidence**: `notrace.json`
+2. **Inspect**: `notrace.html`
+3. **Review outcome**: `notrace.review.json`
+4. **Compare attempts**: `compare:notrace`
+
+## Storage
+
+```text
+.notrace/
+  index.json
+  index.html
+  sessions/
+    <session-id>/
+      notrace.json
+      notrace.html
+      notrace.review.json
 ```
-🔍 [notrace] Observability artifacts generated:
-📂 file:///path/to/.notrace/sessions/<session-id>/notrace.html
-📂 file:///path/to/.notrace/sessions/<session-id>/notrace.json
-```
 
-## Usage
+## Canonical run model
+
+Generated `notrace.json` is the source of truth for runtime output, HTML rendering, and downstream tooling.
+The record is versioned and centers on:
+- `kind`
+- `schemaVersion`
+- `traceId`
+- `repository`
+- `session`
+- `task`
+- `captureMode`
+- `conditions`
+- `activity`
+- `telemetry`
+- `events`
+
+Key rule:
+- **consumed tokens** and **saved tokens** are separate metric families
+- optimization telemetry belongs under `telemetry.extensions.*`
+- presentation-only UI strings are not canonical evidence
+
+## Dynamic extension telemetry
+
+`notrace` can include optional structured telemetry from dynamic extensions.
+Current first target is `noheadroom`.
+
+If an extension is absent, `notrace` should still succeed.
+If an extension is present, it can contribute a structured summary such as:
+- loaded / enabled / active state
+- optimization attempts
+- tokens saved
+- last applied compression summary
+
+## Capture modes
+
+Default capture mode is **full**.
 
 ```bash
-# Load directly
 pi --extension ./packages/notrace
-
-# Via nothing mindset (dev, rpiv)
-pi --dev
 ```
 
-## NPM
+Optional modes:
 
 ```bash
-npm install -g @raquezha/notrace
+NOTRACE_CAPTURE=redacted pi --extension ./packages/notrace
+NOTRACE_CAPTURE=metadata pi --extension ./packages/notrace
+NOTRACE_CAPTURE=full pi --extension ./packages/notrace
 ```
 
-## Add a human review
+Mode meanings:
+- `full`: full captured payloads; best for local debugging; highest sensitivity
+- `redacted`: captured payloads with common secret-like values redacted
+- `metadata`: minimal capture, no prompt/tool bodies
+
+**Security warning:** even redacted reports can contain sensitive prompts, tool payloads, local paths, and outputs. Do not publish generated reports.
+
+## Review
 
 ```bash
-npm run review:notrace -- path/to/notrace.json \
+npm run review:notrace -- \
+  .notrace/sessions/<id>/notrace.json \
   --outcome partial \
   --friction high \
   --lesson "Headroom reduced tokens but needed manual steering." \
   --next-change "Try same task with RepoScry enabled."
 ```
 
-This writes an adjacent review sidecar. For normal runs that means `notrace.review.json` next to `notrace.json`.
-
-If the run is attached to an RPIV task folder with `WORK.md`, the review is also logged into that task's `[LOG]` section as a reference to the notrace artifact.
-
 Review fields:
-
 - `outcome`: `success`, `partial`, `failed`, `abandoned`, `inconclusive`
 - `friction`: `low`, `medium`, `high`
-- `lesson`: short human conclusion
-- `nextChange`: what to try next run
+- `lesson`
+- `nextChange`
 
-## Compare two runs
+## Compare
 
 ```bash
 npm run compare:notrace -- \
-  path/to/baseline/notrace.json \
-  path/to/candidate/notrace.json
+  .notrace/sessions/<baseline-id>/notrace.json \
+  .notrace/sessions/<candidate-id>/notrace.json
 ```
 
-This prints a small retrospective diff for:
+## Templates
 
-- total/input/output tokens
-- duration
-- LLM calls
-- tool calls
-- tool errors
-- total cost
-- model/provider mix
-- review sidecar outcome/friction/lesson when present
+HTML source-of-truth lives in `templates/`:
+- `dashboard.sample.json`
+- `session.sample.json`
+- `dashboard.sample.html`
+- `session.sample.html`
 
-## Capture controls
-
-By default, notrace uses `NOTRACE_CAPTURE=redacted`: it captures useful payloads but redacts common secret keys/values and truncates very large values.
+Refresh previews after renderer changes:
 
 ```bash
-NOTRACE_CAPTURE=metadata pi --dev   # no prompt/tool payload bodies
-NOTRACE_CAPTURE=full pi --dev       # unsafe: raw payloads for local debugging only
+cd packages/notrace
+npm run render:samples
 ```
 
 ## Build

package/assets/notrace-logo.svg

@@ -0,0 +1,20 @@
+<svg viewBox="0 0 420 138" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="notrace">
+  <title>notrace logo</title>
+  <desc>Signal icon above and slightly overlapping the notrace wordmark.</desc>
+  <defs>
+    <linearGradient id="fadeGrad" x1="0%" y1="0%" x2="100%" y2="0%">
+      <stop offset="0%" stop-color="#E2754A"/>
+      <stop offset="100%" stop-color="#EDE2D2"/>
+    </linearGradient>
+  </defs>
+  <g id="trace-icon" transform="translate(1 -5) scale(0.93)">
+    <path d="M6,50 C16,18 26,18 36,50 C46,82 54,82 60,50 C64,30 68,30 71,50"
+      fill="none" stroke="url(#fadeGrad)" stroke-width="4" stroke-linecap="round"/>
+    <line x1="74" y1="50" x2="79" y2="50" stroke="#D9C9B5" stroke-width="4" stroke-linecap="round" stroke-opacity="0.6"/>
+    <circle cx="85" cy="50" r="2.2" fill="#D9C9B5" opacity="0.5"/>
+    <circle cx="90" cy="50" r="1.4" fill="#EDE2D2" opacity="0.32"/>
+    <circle cx="94" cy="50" r="0.9" fill="#EDE2D2" opacity="0.15"/>
+  </g>
+  <text x="0" y="114" fill="#ECE3DA" style="fill:#ECE3DA" font-family="Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, sans-serif" font-size="96" font-weight="900" letter-spacing="-7">no</text>
+  <text x="82" y="114" fill="#D88462" font-family="Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, sans-serif" font-size="96" font-weight="900" letter-spacing="-7">trace</text>
+</svg>

package/assets/notrace-mark.svg

@@ -0,0 +1,18 @@
+<svg width="100" height="100" viewBox="0 0 100 100" xmlns="http://www.w3.org/2000/svg" role="img">
+  <title>notrace logo mark</title>
+  <desc>A wave that smooths into a flat line, then fades into dots — color shifts from trace orange to no cream as it dissolves.</desc>
+  <defs>
+    <linearGradient id="fadeGrad" x1="0%" y1="0%" x2="100%" y2="0%">
+      <stop offset="0%" stop-color="#E2754A"/>
+      <stop offset="100%" stop-color="#EDE2D2"/>
+    </linearGradient>
+  </defs>
+  <g id="trace-icon">
+    <path d="M6,50 C16,18 26,18 36,50 C46,82 54,82 60,50 C64,30 68,30 71,50"
+          fill="none" stroke="url(#fadeGrad)" stroke-width="4" stroke-linecap="round"/>
+    <line x1="74" y1="50" x2="79" y2="50" stroke="#D9C9B5" stroke-width="4" stroke-linecap="round" stroke-opacity="0.6"/>
+    <circle cx="85" cy="50" r="2.2" fill="#D9C9B5" opacity="0.5"/>
+    <circle cx="90" cy="50" r="1.4" fill="#EDE2D2" opacity="0.32"/>
+    <circle cx="94" cy="50" r="0.9" fill="#EDE2D2" opacity="0.15"/>
+  </g>
+</svg>

package/assets/notrace-wordmark.svg

@@ -0,0 +1,4 @@
+<svg viewBox="0 0 420 96" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="notrace wordmark">
+  <text x="0" y="76" fill="#ECE3DA" font-family="Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, sans-serif" font-size="96" font-weight="900" letter-spacing="-7">no</text>
+  <text x="82" y="76" fill="#D88462" font-family="Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, sans-serif" font-size="96" font-weight="900" letter-spacing="-7">trace</text>
+</svg>

package/dist/notrace/adapters.d.ts

@@ -0,0 +1,32 @@
+import type { WorkflowContext } from "./types.js";
+export interface WorkflowAdapter {
+    name: string;
+    detect(cwd: string): boolean;
+    getContext(cwd: string): WorkflowContext | null;
+    attach(context: WorkflowContext, artifacts: {
+        html: string;
+        record: string;
+    }): void;
+}
+export declare class NorpivAdapter implements WorkflowAdapter {
+    name: string;
+    detect(cwd: string): boolean;
+    getContext(cwd: string): WorkflowContext | null;
+    attach(context: WorkflowContext, artifacts: {
+        html: string;
+        record: string;
+    }): void;
+}
+export declare class ResearchAdapter implements WorkflowAdapter {
+    name: string;
+    detect(cwd: string): boolean;
+    getContext(cwd: string): WorkflowContext | null;
+    attach(): void;
+}
+export declare class GenericAdapter implements WorkflowAdapter {
+    name: string;
+    detect(): boolean;
+    getContext(): null;
+    attach(): void;
+}
+export declare function getActiveAdapter(cwd: string): WorkflowAdapter;

package/dist/notrace/adapters.js

@@ -0,0 +1,83 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import * as path from "node:path";
+function appendWorkLogEntry(taskDir, message) {
+    const workMd = path.join(taskDir, "WORK.md");
+    if (!existsSync(workMd))
+        return;
+    try {
+        const text = readFileSync(workMd, "utf-8");
+        const entry = `- ${new Date().toISOString()}: ${message}`;
+        if (!/^(## )?\[LOG\]\s*$/m.test(text)) {
+            writeFileSync(workMd, `${text.trimEnd()}\n\n## [LOG]\n${entry}\n`);
+            return;
+        }
+        const lines = text.split("\n");
+        const logIndex = lines.findIndex(l => /^(## )?\[LOG\]\s*$/.test(l));
+        let nextSection = lines.length;
+        for (let i = logIndex + 1; i < lines.length; i++) {
+            if (/^(## )?\[[A-Z0-9_-]+\]\s*$/.test(lines[i])) {
+                nextSection = i;
+                break;
+            }
+        }
+        const before = lines.slice(0, nextSection);
+        const after = lines.slice(nextSection);
+        before.push(entry);
+        writeFileSync(workMd, `${before.join("\n")}\n${after.join("\n")}`);
+    }
+    catch { }
+}
+export class NorpivAdapter {
+    name = "norpiv";
+    detect(cwd) {
+        return existsSync(path.join(cwd, ".workflow", "active_task.json"));
+    }
+    getContext(cwd) {
+        try {
+            const workflowDir = path.join(cwd, ".workflow");
+            const content = JSON.parse(readFileSync(path.join(workflowDir, "active_task.json"), "utf-8"));
+            const taskPath = content.taskPath || (content.active_task ? path.join("tasks", content.active_task) : null);
+            return {
+                workflow: this.name,
+                taskId: content.active_task || "unknown",
+                taskPath,
+                taskDir: taskPath ? path.resolve(cwd, taskPath) : null
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    attach(context, artifacts) {
+        if (!context.taskDir)
+            return;
+        appendWorkLogEntry(context.taskDir, `notrace retrospective: ${artifacts.html}`);
+    }
+}
+export class ResearchAdapter {
+    name = "research";
+    detect(cwd) {
+        return existsSync(path.join(cwd, ".git")) && !existsSync(path.join(cwd, ".workflow", "active_task.json"));
+    }
+    getContext(cwd) {
+        try {
+            const head = readFileSync(path.join(cwd, ".git", "HEAD"), "utf-8");
+            const branch = head.split("refs/heads/")[1]?.trim() || "main";
+            return { workflow: this.name, taskId: `branch:${branch}`, taskPath: null, taskDir: null };
+        }
+        catch {
+            return null;
+        }
+    }
+    attach() { }
+}
+export class GenericAdapter {
+    name = "generic";
+    detect() { return true; }
+    getContext() { return null; }
+    attach() { }
+}
+const ADAPTERS = [new NorpivAdapter(), new ResearchAdapter(), new GenericAdapter()];
+export function getActiveAdapter(cwd) {
+    return ADAPTERS.find(a => a.detect(cwd)) || new GenericAdapter();
+}

package/dist/notrace/index.d.ts

@@ -0,0 +1,2 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+export default function (pi: ExtensionAPI): void;