@diffexai/diffex 0.2.1 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diffexai/diffex",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Coding agent CLI with read, bash, edit, write, update_plan tools and session management",
   "type": "module",
   "imports": {
@@ -8,7 +8,8 @@
     "#harness-trace": "./dist/vendor/harness-trace/index.js"
   },
   "diffexConfig": {
-    "configDir": ".diffex"
+    "configDir": ".diffex",
+    "production": true
   },
   "bin": {
     "diffex": "dist/cli.js"
@@ -30,11 +31,40 @@
   },
   "files": [
     "dist",
-    "docs",
+    "docs/compaction.md",
+    "docs/containerization.md",
+    "docs/custom-provider.md",
+    "docs/environment-variables.md",
+    "docs/evolution.md",
+    "docs/extensions.md",
+    "docs/installation.md",
+    "docs/json.md",
+    "docs/keybindings.md",
+    "docs/llama-cpp.md",
+    "docs/models.md",
+    "docs/packages.md",
+    "docs/prompt-templates.md",
+    "docs/providers.md",
+    "docs/quickstart.md",
+    "docs/rpc.md",
+    "docs/sdk.md",
+    "docs/security.md",
+    "docs/session-format.md",
+    "docs/sessions.md",
+    "docs/settings.md",
+    "docs/shell-aliases.md",
+    "docs/skills.md",
+    "docs/terminal-setup.md",
+    "docs/themes.md",
+    "docs/tmux.md",
+    "docs/tui.md",
+    "docs/usage.md",
+    "docs/images/interactive-mode.png",
+    "docs/images/tree-view.png",
+    "README.md",
     "CHANGELOG.md",
     "npm-shrinkwrap.json",
     "LICENSE",
-    "NOTICE",
     "THIRD-PARTY-NOTICES.txt",
     "distribution-components.json",
     "distribution-files.json",
@@ -91,12 +121,8 @@
   ],
   "author": "Mario Zechner",
   "license": "Apache-2.0",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/diffexai/diffex.git",
-    "directory": "packages/coding-agent"
-  },
   "engines": {
     "node": ">=22.19.0"
-  }
+  },
+  "homepage": "https://diffex.ai/"
 }

package/release/distribution-manifest.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
-  "version": "0.2.1",
+  "version": "0.2.3",
   "source": {
     "repository": "diffexai/diffex",
-    "commit": "f2a661684af35fe6e9a3209c6f9720144e1fd423",
+    "commit": "a9a2beea7798edd34c62e836d73a0d50b6260950",
     "visibility": "private"
   },
   "disclosurePolicy": {
@@ -43,7 +43,7 @@
       "HTML export templates and their reviewed marked/highlight.js bundles",
       "runtime theme and model JSON",
       "SQLite migration SQL",
-      "documentation including inline examples",
+      "user-facing documentation explicitly listed in scripts/distribution-docs.json",
       "Diffex-owned TUI native prebuilds using system APIs"
     ],
     "publicHosting": "npmjs",
@@ -63,13 +63,14 @@
       "protocol",
       "telemetry",
       "tui"
-    ]
+    ],
+    "developmentDocumentation": "exclude from all distribution artifacts, including bootstrap and hosted runtime; keep private development records in the source repository"
   },
   "packages": [
     {
       "name": "@diffexai/diffex",
-      "version": "0.2.1",
-      "tarball": "https://registry.npmjs.org/@diffexai/diffex/-/diffex-0.2.1.tgz"
+      "version": "0.2.3",
+      "tarball": "https://registry.npmjs.org/@diffexai/diffex/-/diffex-0.2.3.tgz"
     }
   ],
   "binaryPlatforms": [],

package/release/install-package-lock.json

@@ -1,14 +1,14 @@
 {
 	"name": "@diffexai/diffex-coding-agent-install",
-	"version": "0.2.1",
+	"version": "0.2.3",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "@diffexai/diffex-coding-agent-install",
-			"version": "0.2.1",
+			"version": "0.2.3",
 			"dependencies": {
-				"@diffexai/diffex": "0.2.1"
+				"@diffexai/diffex": "0.2.3"
 			},
 			"engines": {
 				"node": ">=22.19.0"
@@ -450,8 +450,8 @@
 			}
 		},
 		"node_modules/@diffexai/diffex": {
-			"version": "0.2.1",
-			"resolved": "https://registry.npmjs.org/@diffexai/diffex/-/diffex-0.2.1.tgz",
+			"version": "0.2.3",
+			"resolved": "https://registry.npmjs.org/@diffexai/diffex/-/diffex-0.2.3.tgz",
 			"license": "Apache-2.0",
 			"dependencies": {
 				"@anthropic-ai/sdk": "0.91.1",

package/release/install-package.json

@@ -1,10 +1,10 @@
 {
 	"name": "@diffexai/diffex-coding-agent-install",
-	"version": "0.2.1",
+	"version": "0.2.3",
 	"private": true,
 	"description": "Lockfile root used by the Diffex installer and updater.",
 	"dependencies": {
-		"@diffexai/diffex": "0.2.1"
+		"@diffexai/diffex": "0.2.3"
 	},
 	"overrides": {
 		"protobufjs": "7.6.5",

package/NOTICE

@@ -1,6 +0,0 @@
-Diffex
-Copyright 2026 Luntraa, Inc.
-
-Where this distribution contains Pi Agent Harness-derived portions,
-those portions retain their MIT terms and copyright notice in LICENSE.
-The Apache-2.0 package declaration does not replace third-party terms.

package/dist/node_modules/@diffexai/diffex-agent-core/NOTICE

@@ -1,6 +0,0 @@
-Diffex
-Copyright 2026 Luntraa, Inc.
-
-Where this distribution contains Pi Agent Harness-derived portions,
-those portions retain their MIT terms and copyright notice in LICENSE.
-The Apache-2.0 package declaration does not replace third-party terms.

package/dist/node_modules/@diffexai/diffex-ai/NOTICE

@@ -1,6 +0,0 @@
-Diffex
-Copyright 2026 Luntraa, Inc.
-
-Where this distribution contains Pi Agent Harness-derived portions,
-those portions retain their MIT terms and copyright notice in LICENSE.
-The Apache-2.0 package declaration does not replace third-party terms.

package/dist/node_modules/@diffexai/diffex-client/NOTICE

@@ -1,6 +0,0 @@
-Diffex
-Copyright 2026 Luntraa, Inc.
-
-Where this distribution contains Pi Agent Harness-derived portions,
-those portions retain their MIT terms and copyright notice in LICENSE.
-The Apache-2.0 package declaration does not replace third-party terms.

package/dist/node_modules/@diffexai/diffex-harness-state/NOTICE

@@ -1,6 +0,0 @@
-Diffex
-Copyright 2026 Luntraa, Inc.
-
-Where this distribution contains Pi Agent Harness-derived portions,
-those portions retain their MIT terms and copyright notice in LICENSE.
-The Apache-2.0 package declaration does not replace third-party terms.

package/dist/node_modules/@diffexai/diffex-protocol/NOTICE

@@ -1,6 +0,0 @@
-Diffex
-Copyright 2026 Luntraa, Inc.
-
-Where this distribution contains Pi Agent Harness-derived portions,
-those portions retain their MIT terms and copyright notice in LICENSE.
-The Apache-2.0 package declaration does not replace third-party terms.

package/dist/node_modules/@diffexai/diffex-telemetry/NOTICE

@@ -1,6 +0,0 @@
-Diffex
-Copyright 2026 Luntraa, Inc.
-
-Where this distribution contains Pi Agent Harness-derived portions,
-those portions retain their MIT terms and copyright notice in LICENSE.
-The Apache-2.0 package declaration does not replace third-party terms.

package/dist/node_modules/@diffexai/diffex-tui/NOTICE

@@ -1,6 +0,0 @@
-Diffex
-Copyright 2026 Luntraa, Inc.
-
-Where this distribution contains Pi Agent Harness-derived portions,
-those portions retain their MIT terms and copyright notice in LICENSE.
-The Apache-2.0 package declaration does not replace third-party terms.

package/docs/development.md

@@ -1,71 +0,0 @@
-# Development
-
-See [AGENTS.md](https://github.com/diffexai/diffex/blob/main/AGENTS.md) for additional guidelines.
-
-## Setup
-
-```bash
-git clone https://github.com/diffexai/diffex
-cd diffex
-npm install
-npm run build
-```
-
-Run from source:
-
-```bash
-/path/to/diffex/diffex-test.sh
-```
-
-The script can be run from any directory. Diffex keeps the caller's current working directory.
-
-## Forking / Rebranding
-
-Configure via `package.json`:
-
-```json
-{
-  "diffexConfig": {
-    "name": "diffex",
-    "configDir": ".diffex"
-  }
-}
-```
-
-Change `name`, `configDir`, and `bin` field for your fork. Affects CLI banner, config paths, and environment variable names.
-
-## Path Resolution
-
-Three execution modes: npm install, standalone binary, tsx from source.
-
-**Always use `src/config.ts`** for package assets:
-
-```typescript
-import { getPackageDir, getThemeDir } from "./config.js";
-```
-
-Never use `__dirname` directly for package assets.
-
-## Debug Command
-
-`/debug` (hidden) writes to `~/.diffex/agent/diffex-debug.log`:
-- Rendered TUI lines with ANSI codes
-- Last messages sent to the LLM
-
-## Testing
-
-```bash
-./test.sh                         # Run non-LLM tests (no API keys needed)
-npm test                          # Run all tests
-npm test -- test/specific.test.ts # Run specific test
-```
-
-## Project Structure
-
-```
-packages/
-  ai/           # LLM provider abstraction
-  agent/        # Agent loop and message types  
-  tui/          # Terminal UI components
-  coding-agent/ # CLI and interactive mode
-```

package/docs/docs.json

@@ -1,160 +0,0 @@
-{
-  "navigation": [
-    {
-      "title": "Start here",
-      "items": [
-        {
-          "title": "Overview",
-          "path": "index.md"
-        },
-        {
-          "title": "Quickstart",
-          "path": "quickstart.md"
-        },
-        {
-          "title": "Using Diffex",
-          "path": "usage.md"
-        },
-        {
-          "title": "Providers",
-          "path": "providers.md"
-        },
-        {
-          "title": "Security",
-          "path": "security.md"
-        },
-        {
-          "title": "Containerization",
-          "path": "containerization.md"
-        },
-        {
-          "title": "Settings",
-          "path": "settings.md"
-        },
-        {
-          "title": "Harness Evolution",
-          "path": "evolution.md"
-        },
-        {
-          "title": "Keybindings",
-          "path": "keybindings.md"
-        },
-        {
-          "title": "Sessions",
-          "path": "sessions.md"
-        },
-        {
-          "title": "Compaction",
-          "path": "compaction.md"
-        }
-      ]
-    },
-    {
-      "title": "Customization",
-      "items": [
-        {
-          "title": "Extensions",
-          "path": "extensions.md"
-        },
-        {
-          "title": "Skills",
-          "path": "skills.md"
-        },
-        {
-          "title": "Prompt Templates",
-          "path": "prompt-templates.md"
-        },
-        {
-          "title": "Themes",
-          "path": "themes.md"
-        },
-        {
-          "title": "Diffex Packages",
-          "path": "packages.md"
-        },
-        {
-          "title": "Custom Models",
-          "path": "models.md"
-        },
-        {
-          "title": "Custom Providers",
-          "path": "custom-provider.md"
-        }
-      ]
-    },
-    {
-      "title": "Reference",
-      "items": [
-        {
-          "title": "Session Format",
-          "path": "session-format.md"
-        }
-      ]
-    },
-    {
-      "title": "Programmatic Usage",
-      "items": [
-        {
-          "title": "SDK",
-          "path": "sdk.md"
-        },
-        {
-          "title": "RPC Mode",
-          "path": "rpc.md"
-        },
-        {
-          "title": "JSON Event Stream Mode",
-          "path": "json.md"
-        },
-        {
-          "title": "TUI Components",
-          "path": "tui.md"
-        }
-      ]
-    },
-    {
-      "title": "Platform Setup",
-      "items": [
-        {
-          "title": "Windows",
-          "path": "windows.md"
-        },
-        {
-          "title": "Termux on Android",
-          "path": "termux.md"
-        },
-        {
-          "title": "tmux",
-          "path": "tmux.md"
-        },
-        {
-          "title": "Terminal Setup",
-          "path": "terminal-setup.md"
-        },
-        {
-          "title": "Shell Aliases",
-          "path": "shell-aliases.md"
-        }
-      ]
-    },
-    {
-      "title": "Development",
-      "items": [
-        {
-          "title": "Development",
-          "path": "development.md"
-        }
-      ]
-    }
-  ],
-  "redirects": [
-    {
-      "from": "session.md",
-      "to": "session-format.md"
-    },
-    {
-      "from": "tree.md",
-      "to": "sessions.md"
-    }
-  ]
-}

package/docs/index.md

@@ -1,78 +0,0 @@
-# Diffex Documentation
-
-Diffex is a minimal terminal coding harness. It is designed to stay small at the core while being extended through TypeScript extensions, skills, prompt templates, themes, and Diffex packages.
-
-## Quick start
-
-Install Diffex with npm:
-
-```bash
-npm install -g --ignore-scripts @diffexai/diffex
-```
-
-`--ignore-scripts` disables dependency lifecycle scripts during install. Diffex does not require install scripts for normal npm installs.
-
-To uninstall Diffex, use the matching package manager. For npm installs:
-
-```bash
-npm uninstall -g @diffexai/diffex
-```
-
-For pnpm, Yarn, or Bun installs, use the matching global remove command: `pnpm remove -g @diffexai/diffex`, `yarn global remove @diffexai/diffex`, or `bun uninstall -g @diffexai/diffex`.
-
-Then run it in a project directory:
-
-```bash
-diffex
-```
-
-Authenticate with `/login` for subscription providers, or set an API key such as `ANTHROPIC_API_KEY` before starting Diffex.
-
-For the full first-run flow, see [Quickstart](quickstart.md).
-
-## Start here
-
-- [Quickstart](quickstart.md) - install, authenticate, and run a first session.
-- [Using Diffex](usage.md) - interactive mode, slash commands, context files, and CLI reference.
-- [Providers](providers.md) - subscription and API-key setup for built-in providers.
-- [llama.cpp](llama-cpp.md) - run a local router and manage models with `/llama`.
-- [Security](security.md) - project trust, sandbox boundaries, and vulnerability reporting.
-- [Containerization](containerization.md) - sandbox Diffex with Docker or OpenShell.
-- [Settings](settings.md) - global and project settings.
-- [Keybindings](keybindings.md) - default shortcuts and custom keybindings.
-- [Sessions](sessions.md) - session management, branching, and tree navigation.
-- [Compaction](compaction.md) - context compaction and branch summarization.
-
-## Customization
-
-- [Extensions](extensions.md) - TypeScript modules for tools, commands, events, and custom UI.
-- [Skills](skills.md) - Agent Skills for reusable on-demand capabilities.
-- [Prompt templates](prompt-templates.md) - reusable prompts that expand from slash commands.
-- [Themes](themes.md) - built-in and custom terminal themes.
-- [Diffex packages](packages.md) - bundle and share extensions, skills, prompts, and themes.
-- [Custom models](models.md) - add model entries for supported provider APIs.
-- [Custom providers](custom-provider.md) - implement custom APIs and OAuth flows.
-
-## Programmatic usage
-
-- [SDK](sdk.md) - embed Diffex in Node.js applications.
-- [RPC mode](rpc.md) - integrate over stdin/stdout JSONL.
-- [JSON event stream mode](json.md) - print mode with structured events.
-- [TUI components](tui.md) - build custom terminal UI for extensions.
-
-## Reference
-
-- [Environment variables](environment-variables.md) - Diffex process configuration and session metadata available to bash tools.
-- [Session format](session-format.md) - JSONL session file format, entry types, and SessionManager API.
-
-## Platform setup
-
-- [Windows](windows.md)
-- [Termux on Android](termux.md)
-- [tmux](tmux.md)
-- [Terminal setup](terminal-setup.md)
-- [Shell aliases](shell-aliases.md)
-
-## Development
-
-- [Development](development.md) - local setup, project structure, and debugging.

package/docs/invocation-traces.md

@@ -1,82 +0,0 @@
-# Invocation Traces
-
-Diffex creates immutable invocation trace intervals for each CLI process whose initial session is persisted.
-An interval closes as soon as its operations settle, so a running peer can discover completed evidence without reading a trace that is still changing.
-Concurrent operations in one process share an interval until every operation in that interval settles.
-Ephemeral commands such as `--no-session`, `--help`, and `--list-models` do not create traces.
-
-Trace creation is passive.
-If the trace file cannot be created, Diffex prints one warning and continues without durable telemetry.
-
-## Storage and Discovery
-
-Trace files are stored in `~/.diffex/agent/evolution-workspaces/<workspace-id>/traces/` by default, or under the corresponding workspace directory beneath `DIFFEX_CODING_AGENT_DIR`.
-Each file is named `<UTC timestamp>_<trace ID>.jsonl`.
-A long-running process can create multiple files as successive operations settle.
-The trace directory is restricted to the current user with mode `0700`, and each trace file uses mode `0600` on POSIX systems.
-
-Tools can discover a workspace's traces by scanning its trace directory for `.jsonl` files and validating them with the harness trace reader. Trace directories are intentionally separate: sessions in the same workspace contribute to the same evidence stream, while another workspace has independent invocation ordering, reported token totals, and evolution jobs.
-The trace header identifies the producing Diffex build and runtime.
-Session attachment records identify every referenced session ID, path, format, and transition reason.
-
-## Retention and Session Changes
-
-Traces are retained until the user explicitly removes them.
-Diffex does not currently apply an automatic age or size limit.
-
-Deleting a session does not delete its traces.
-Moving or renaming a session does not rewrite existing trace references.
-This preserves invocation evidence while allowing readers to report that referenced session content is missing or moved.
-
-Trace files contain execution telemetry and immutable session entry references, not duplicated transcript content.
-
-## Evidence Ownership
-
-Each fact has one authoritative source so a trace remains compact and materialization does not create competing copies.
-
-| Source | Authoritative facts | Materialized form |
-| --- | --- | --- |
-| Coding-agent v3 session JSONL | Messages, assistant tool calls, tool results, message usage, model and thinking changes, compaction and branch summaries, custom extension entries, labels, and session metadata | `session_item` evidence selected by entry ordinal, entry ID, and digest |
-| AgentHarness session JSONL | Durable entries, operation admission and settlement, abort requests, retry attempts, tool admission, queue changes, deferred writes, usage, lane pointers, and session facts | `session_item` evidence selected by durable session sequence |
-| Agent and AI telemetry spans | Agent runs, turns, logical provider requests, provider outcomes, tool execution outcomes, usage, and causal invocation, turn, request, and tool-call identifiers | Consolidated `span` evidence |
-| Coding-agent and extension telemetry spans | User-visible operations, retries and sleeps, extension hook outcomes, subagent coordination, terminal commands, external artifact references, and runtime diagnostics | Consolidated `span` evidence |
-| Trace lifecycle records | Producer identity, session bindings, harness activation, session segments, trace writer degradation, and completed, failed, or aborted interval termination | `trace_record` evidence and document diagnostics |
-| Missing trace footer | A process that did not close its active interval orderly | A `crashed` materialized termination status with a missing-footer diagnostic |
-
-Agent and extension events remain live notification APIs.
-Their durable facts are represented by the owning session entry, session record, or telemetry span listed above rather than by copying event payloads into the trace.
-
-Prompt and queue operation spans record one event per immutable skill identity for these observable facts:
-
-- `diffex.skill.available`: the installed or evolved version was available when the request was admitted
-- `diffex.skill.listed`: the version appeared in the system prompt sent to the model
-- `diffex.skill.selected`: an automatic selector returned the version, when such a selector is used
-- `diffex.skill.explicitly_referenced`: the admitted user request contained its versioned reference
-- `diffex.skill.force_loaded`: a `/skills` reference expanded its captured content into the request
-- `diffex.skill.read`: the model-callable `read` tool successfully read content whose path and digest match the catalog version
-
-Each event includes the skill ID, version, content digest, source kind, source, scope, and, when configured, the active workspace identity and applicable skill and active harness revisions. Prompt spans carry the top-level task-lineage identifier, and queue spans admitted during a task remain nested beneath that prompt; retries, tool calls, subagents, and repeated reads therefore remain observable within the same top-level lineage. Tool results and terminal operation outcomes remain independent evidence. Traces never emit an inferred `used` event or treat listing, selection, loading, reading, or co-occurrence as proof that a skill caused an outcome.
-
-Startup and configuration failures are recorded as runtime diagnostic spans after trace creation.
-Failures that prevent trace creation remain an explicit limitation because no durable trace destination exists.
-
-## Materialization
-
-`materializeJsonlInvocation()` reads and validates a trace, resolves every referenced session binding, verifies each segment boundary, and returns a versioned `MaterializedInvocation` document.
-The optional session path resolver can locate a session that moved after the trace was written while preserving both its recorded and resolved paths.
-
-Coding-agent v3 content digests are SHA-256 hashes of `JSON.stringify(entry)`.
-Prefix digests are SHA-256 hashes of the LF-framed canonical entry JSON from the first non-header entry through the referenced entry.
-AgentHarness segments use inclusive durable session sequence bounds.
-
-The materializer embeds only session items referenced by trace segments.
-It preserves message and tool payloads exactly as stored in the session, combines span starts, events, and settlements, and retains every contributing trace record ID, span ID, session binding ID, session entry ID, and session sequence.
-
-Evidence is ordered deterministically by trace sequence, session cursor, timestamp, span parentage, and causal identifiers.
-Session cursor order is durable inside a segment, but the document reports ordering ambiguity when clocks and segment boundaries cannot establish a total order with trace records.
-
-Missing, changed, truncated, or incompatible session data produces diagnostics without discarding valid trace records or earlier session evidence.
-Writer-degraded and crashed traces likewise produce partial documents instead of failing materialization.
-
-`serializeMaterializedInvocation()` emits stable, indented JSON with a trailing newline for storage or bounded LLM analysis.
-The materialized document contains evidence only and does not include extracted claims, evolution proposals, approval state, or behavior mutations.