llm-trace 0.1.1 → 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,29 +1,55 @@
 # llm-trace
 
+[![npm version](https://img.shields.io/npm/v/llm-trace.svg)](https://www.npmjs.com/package/llm-trace)
+[![CI](https://github.com/moondef/llm-trace/actions/workflows/ci.yml/badge.svg)](https://github.com/moondef/llm-trace/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 LLMs can read your code but they can't run it in their head. When something breaks, they end up asking you to paste errors and add `console.log` statements one at a time while they guess at what's going on.
 
 llm-trace fixes this. It gives LLMs a way to instrument your code with structured traces, see actual runtime values, and figure out what went wrong without the back-and-forth.
 
-## Try It
+## Install
+
+Install the [debugging skill](skills/debugging-with-llm-trace/SKILL.md) so your LLM tool knows how to use llm-trace. The skill will ask to `npm install llm-trace` into your project — it's the SDK that provides the `trace()`, `span()`, and `checkpoint()` calls for code instrumentation.
+
+**Claude Code:**
+```bash
+/plugin marketplace add moondef/llm-trace
+/plugin install debugging-with-llm-trace@llm-trace
+```
+
+**Codex:**
+```
+$skill-installer install https://github.com/moondef/llm-trace/tree/main/skills/debugging-with-llm-trace
+```
+
+**Any tool** (via npx):
+```bash
+npx skills add moondef/llm-trace
+```
 
+**Or clone and copy manually:**
 ```bash
-npm install llm-trace
+git clone https://github.com/moondef/llm-trace.git
+cp -r llm-trace/skills/debugging-with-llm-trace ~/.claude/skills/
 ```
 
-Add the [debugging skill](skills/debugging-with-llm-trace/SKILL.md) to Claude Code (or any LLM coding tool) and ask it to debug something. That's it — the skill teaches it the workflow.
+## Usage
 
-### What happens next
+Just ask your LLM to debug something. The skill handles the rest.
 
-You tell the LLM "this endpoint returns 500 sometimes" and it:
+You say "this endpoint returns 500 sometimes" and it:
 
-1. Runs `npx llm-trace start`
-2. Wraps the endpoint in `trace()` with `span()` and `checkpoint()` calls
-3. Triggers the bug
-4. Reads the trace — sees actual values at each step, which span failed, the error
+1. Starts a tracing session (`llm-trace start`)
+2. Instruments the suspect code with `trace()`, `span()`, and `checkpoint()`
+3. Runs the code to trigger the bug
+4. Reads the trace — actual values at each step, which span failed, the error
 5. Fixes the root cause based on what it saw
-6. Removes instrumentation, runs `npx llm-trace stop`
+6. Cleans up instrumentation and stops the session
 
-## Three Primitives
+## What It Captures
+
+Three primitives, all the LLM needs:
 
 ```typescript
 import { trace } from "llm-trace";
@@ -46,7 +72,7 @@ await trace("checkout", async (handle) => {
 
 **`handle.span(name, fn)`** — a timed step within a trace. Nests to any depth.
 
-**`handle.checkpoint(name, data?)`** — snapshots a value (truncated at 64KB).
+**`handle.checkpoint(name, data?)`** — snapshots a value at a point in time (truncated at 64KB).
 
 Errors are captured automatically — if anything throws, the trace records the error and stack.
 
@@ -63,9 +89,9 @@ llm-trace stop              # end session, delete traces
 
 Output is JSON by default (for LLM consumption). Add `--human` for readable output.
 
-## How It Fits Together
+## How It Works
 
-The LLM writes `trace()` / `span()` / `checkpoint()` calls into your code. When the code runs, events stream over HTTP to a local server that writes `.ndjson` files. The LLM reads those files via the CLI. After debugging, everything is cleaned up — traces are ephemeral.
+The LLM writes `trace()` / `span()` / `checkpoint()` calls into your code. When the code runs, events stream over HTTP to a local server that writes `.ndjson` files. The LLM reads those files via the CLI. After debugging, everything gets cleaned up — traces are ephemeral.
 
 No dependencies. No config. Nothing persisted after `stop`.
 
@@ -74,3 +100,7 @@ No dependencies. No config. Nothing persisted after `stop`.
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `LLM_TRACE_PORT` | `13579` | HTTP server port |
+
+## Contributing
+
+Issues and PRs welcome at [github.com/moondef/llm-trace](https://github.com/moondef/llm-trace).

package/dist/index.cjs

@@ -1,5 +1,4 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-let node_crypto = require("node:crypto");
 
 //#region src/utils/errors.ts
 function serializeError(err) {
@@ -133,7 +132,11 @@ function createSystemClock() {
 //#region src/utils/id.ts
 function createCryptoIdGenerator() {
 	return { generate(prefix) {
-		return `${prefix}-${(0, node_crypto.randomBytes)(4).toString("hex").slice(0, 6)}`;
+		const bytes = new Uint8Array(3);
+		crypto.getRandomValues(bytes);
+		let suffix = "";
+		for (const b of bytes) suffix += b.toString(16).padStart(2, "0");
+		return `${prefix}-${suffix}`;
 	} };
 }
 

package/dist/index.js

@@ -1,5 +1,3 @@
-import { randomBytes } from "node:crypto";
-
 //#region src/utils/errors.ts
 function serializeError(err) {
 	if (err instanceof Error) return {
@@ -132,7 +130,11 @@ function createSystemClock() {
 //#region src/utils/id.ts
 function createCryptoIdGenerator() {
 	return { generate(prefix) {
-		return `${prefix}-${randomBytes(4).toString("hex").slice(0, 6)}`;
+		const bytes = new Uint8Array(3);
+		crypto.getRandomValues(bytes);
+		let suffix = "";
+		for (const b of bytes) suffix += b.toString(16).padStart(2, "0");
+		return `${prefix}-${suffix}`;
 	} };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-trace",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "private": false,
   "description": "Structured execution traces for LLM debugging",
   "license": "MIT",