@oneciel-ai/ciel-runtime 0.2.22 → 0.2.23

package/CHANGELOG.md

@@ -0,0 +1,108 @@
+# Changelog
+
+This file records stable Ciel Runtime releases. Changes are grouped by user-visible
+capability, followed by the complete commit ledger merged into each release.
+
+## 0.2.23 — 2026-08-23
+
+This release promotes 41 commits developed and validated after `0.2.22`. The
+range changes 110 files with 9,990 insertions and 256 deletions.
+
+### Workspace memory and remote context
+
+- Isolated downloaded memory by launch workspace instead of sharing one global tree.
+- Synchronized manifest-defined memory into the actual runtime working directory.
+- Added atomic download/overwrite support for OKF, Markdown, JSON, YAML, TOML, and text files.
+- Appended verified memory-root/index guidance to native instructions and routed system context.
+- Kept the memory pointer last through instruction refresh and wire-level prompt truncation.
+- Projected memory paths relative to the workspace so replicated projects remain portable.
+
+### External messages and terminal delivery
+
+- Restored complete routed SSE message bodies in Codex wake prompts.
+- Added prompt-render detection and bounded retry for cold-start and deferred Windows ConPTY submissions.
+- Preserved Unicode, whitespace, prompt offsets, and submitted-turn evidence across retries.
+- Isolated Windows installer state and repaired stale temporary runtime pins.
+- Preserved parallel tool results and rejected invalid replayed tool names before upstream submission.
+- Recovered turns stopped by the repeated-tool guard without repeating the completed side effect.
+- Restored Claude's stateless internal Ciel MCP launch configuration and `/ca/mcp` POST tool endpoint.
+
+### Transcripts and compaction
+
+- Added incremental transcript-delta webhooks with CloudEvents, durable cursors, retry, and compaction-boundary events.
+- Sanitized legacy Anthropic history containing empty `tool_use.name` values so affected sessions can compact and continue.
+
+### Providers and models
+
+- Aligned Alibaba Model Studio Singapore `qwen3.8-max` context limits and workspace endpoint migration.
+- Kept Alibaba OpenAI-compatible and Anthropic-compatible request wires distinct.
+- Added OpenRouter and OpenCode Zen/Go routes for Ox Alpha/free catalog aliases.
+- Forwarded supported OpenRouter reasoning-effort values instead of dropping them.
+- Added the TaBiAI/Tabitoken provider with separate Anthropic Messages and OpenAI Chat endpoints and its verified model catalog.
+
+### Usage observability
+
+- Added a workspace-scoped SQLite usage ledger for routed requests.
+- Added authenticated event, resumable SSE stream, and time-range snapshot endpoints.
+- Added per-consumer API keys with scopes, expiry, digest-only storage, and revocation.
+- Added outbound CloudEvent delivery with per-endpoint durable cursors, stable idempotency keys, and retry after failed delivery.
+- Added interval audit snapshots, including a daily default, grouped by provider, model, and runtime.
+- Added rotation-safe backfill from earlier workspace JSONL usage logs and explicit legacy paths.
+- Added equivalent startup environment variables and persistent `ciel-runtimectl` configuration commands.
+
+### Documentation and verification
+
+- Added evidence journals for WING, delluhiold, Hyundai, Alibaba, OpenRouter,
+  TaBiAI, remote memory, transcript delivery, and usage observability incidents.
+- Made usage backfill tests platform-native so the same contract passes on Windows and Linux CI.
+
+### Complete commit ledger
+
+Every audited pre-release commit between `0.2.22` (`b7ea382`) and the release
+preparation commit is listed below in chronological order.
+
+- `60866dc` docs: trace external SSE wake-only delivery
+- `13f5d91` fix: isolate remote memory to project workspaces
+- `5e5bdec` fix: load remote memory from workspace state
+- `6648365` fix: sync remote memory into launch workspace
+- `21872ed` fix: keep memory pointer last in system prompt
+- `c4071ef` fix: restore memory pointer after wire truncation
+- `72a2474` fix: show routed SSE bodies in Codex wakes
+- `98665f2` docs: record WING SSE wake verification
+- `fc290a0` fix: retry Codex wake submission on ConPTY
+- `b410b4c` fix: wait for Codex prompt render before submit
+- `e4b86e6` docs: record Codex wake submit verification
+- `fe7c4b0` feat: align Alibaba Singapore Qwen3.8
+- `c8d920e` docs: record Qwen3.8 nightly verification
+- `4eab5fb` docs: record runtime deployment diagnostics
+- `5d24d79` fix: preserve parallel tool turns in routed sessions
+- `5a43567` fix: repair stale Windows runtime pins
+- `f6f7a27` fix: isolate Windows installer state
+- `511148d` fix: drop invalid replayed tool names
+- `87525c6` fix: wait for cold-start wake render
+- `fad60f5` fix: track ConPTY prompt render offsets
+- `f357b91` fix: retry deferred wake submissions
+- `39f1119` fix: preserve wake render whitespace
+- `46d0e4e` docs: record WING wake submission verification
+- `bbf2181` fix: recover repeated tool guard turns
+- `b70a228` feat: stream transcript deltas to webhooks
+- `d7d9369` fix: sanitize invalid Anthropic tool history
+- `5223153` docs: record delluhiold compaction verification
+- `f62a72c` docs: record live compaction recovery
+- `ce72ccc` fix: align Alibaba dual endpoint request wires
+- `28ef138` feat: append remote memory guidance to system context
+- `22a3006` fix: project remote memory paths relative to workspace
+- `849814b` feat: add Ox Alpha provider routes
+- `70c5d32` fix: sync OpenCode model endpoint catalog
+- `65e69f1` docs: record Ox Alpha deployment evidence
+- `c243e75` fix: forward OpenRouter reasoning effort
+- `c37d0e4` docs: record OpenRouter effort deployment
+- `d81eb00` feat: add Tabitoken provider
+- `f98310b` docs: record Tabitoken deployment
+- `4d1b68d` feat: add durable usage observability
+- `45a9456` test: use platform-native backfill paths
+- `549e6a6` docs: record usage observability deployment
+
+## 0.2.22 — 2026-08-20
+
+- Published the previous stable runtime baseline. See commit `b7ea382`.

package/README.md

@@ -1,24 +1,38 @@
+<div align="center">
+
 # Ciel Runtime
 
-Ciel Runtime is a cross-platform launcher and local model-routing layer for AI coding agents. It can launch Claude Code, Codex, Codex App Server, or AGY and connect them to native or OpenAI-compatible model providers through one configuration.
+**Run the coding agent you want on the model provider you choose.**
+
+Ciel Runtime is a cross-platform launcher, local protocol router, and workspace
+control plane for Claude Code, Codex, Codex App Server, AGY, Grok Build, and
+compatible AI coding-agent CLIs.
+
+[![npm](https://img.shields.io/npm/v/@oneciel-ai/ciel-runtime?label=npm)](https://www.npmjs.com/package/@oneciel-ai/ciel-runtime)
+[![CI](https://github.com/OneCielAI/ciel-runtime/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/OneCielAI/ciel-runtime/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Node.js 18+](https://img.shields.io/badge/node-%3E%3D18-339933?logo=node.js&logoColor=white)](package.json)
+[![Python 3.10+](https://img.shields.io/badge/python-%3E%3D3.10-3776AB?logo=python&logoColor=white)](docs/Installation.md)
 
-## Features
+[Install](#install) · [Quickstart](#quickstart) · [Capabilities](#what-ciel-runtime-does) · [Providers](docs/Providers.md) · [CLI reference](docs/CLI-Reference.md) · [Changelog](CHANGELOG.md)
 
-- Launch Claude Code, Codex, Codex App Server, and AGY from one CLI.
-- Route Anthropic Messages, OpenAI Chat/Responses, and Ollama-compatible traffic.
-- Select models and providers without rewriting each agent's configuration.
-- Rotate API keys and observe provider rate limits.
-- Normalize tool calls, thinking blocks, streaming events, and context limits.
-- Deliver Web Chat and explicit Ciel messages to active agent sessions.
-- Run on Windows, macOS, and Linux.
+</div>
 
-## Requirements
+## Why Ciel Runtime
 
-- Node.js 18 or newer when installed from npm.
-- Python 3.10 or newer.
-- At least one supported coding-agent CLI or the credentials for the provider you intend to use.
+Coding-agent CLIs and model APIs do not all speak the same protocol. Ciel
+Runtime keeps the native CLI experience while handling provider selection,
+protocol translation, model metadata, workspace context, message delivery, and
+operational telemetry in one local runtime.
 
-The npm launcher searches for `py -3`, `python`, or `python3`. Set `CIEL_RUNTIME_PYTHON` to use a specific Python executable.
+Use it when you need to:
+
+- run multiple coding-agent CLIs without maintaining separate provider setups;
+- connect Anthropic, OpenAI-compatible, Ollama, and provider-specific APIs;
+- keep tools, thinking, streaming, and context behavior intact across protocol boundaries;
+- synchronize project-scoped instructions and memory before every launch;
+- deliver external messages to active sessions and export transcript deltas;
+- audit routed token usage without storing prompts or provider credentials.
 
 ## Install
 
@@ -26,40 +40,46 @@ The npm launcher searches for `py -3`, `python`, or `python3`. Set `CIEL_RUNTIME
 npm install -g @oneciel-ai/ciel-runtime
 ```
 
-The package installs these commands:
+The package installs three commands:
 
-- `ciel-runtime` and `cielrt`: configure and launch an agent.
-- `ciel-runtimectl`: inspect or change runtime configuration.
-- `ciel-runtime-stop`: stop the managed local router.
+| Command | Purpose |
+|---|---|
+| `ciel-runtime` / `cielrt` | Configure and launch an agent runtime |
+| `ciel-runtimectl` | Inspect and change providers, models, memory, events, and router settings |
+| `ciel-runtime-stop` | Stop the managed local router |
 
-Manual installation instructions are available in [docs/Installation.md](docs/Installation.md).
+Requirements: Node.js 18 or newer, Python 3.10 or newer, and at least one
+supported coding-agent CLI or provider credential. Set `CIEL_RUNTIME_PYTHON` to
+select a specific Python executable. See the [installation guide](docs/Installation.md)
+for shell installers, unattended setup, and diagnostics.
 
-## Quick start
+## Quickstart
 
-Select a provider and model interactively:
+Start the interactive setup and launch Claude Code:
 
 ```sh
 ciel-runtime
 ```
 
-Or configure them explicitly:
+Or configure a provider explicitly:
 
 ```sh
 ciel-runtimectl provider openrouter
 ciel-runtimectl set-api-key openrouter YOUR_API_KEY
 ciel-runtimectl model MODEL_ID
+ciel-runtime
 ```
 
-Launch a specific runtime:
+Launch another runtime while preserving its remaining CLI arguments:
 
 ```sh
-ciel-runtime                 # Claude Code by default
 ciel-runtime codex
 ciel-runtime agy
-ciel-runtime codex-app-server
+ciel-runtime grok
+ciel-runtime --ca-runtime codex-app-server
 ```
 
-Inspect the active configuration and router status:
+Check the effective configuration and upstream compatibility:
 
 ```sh
 ciel-runtimectl status
@@ -67,70 +87,143 @@ ciel-runtimectl models
 ciel-runtimectl test
 ```
 
-See [docs/CLI-Reference.md](docs/CLI-Reference.md) for the complete command reference and [docs/Providers.md](docs/Providers.md) for provider-specific options.
+## What Ciel Runtime does
+
+| Capability | What it provides |
+|---|---|
+| Runtime launch | Claude Code, Codex, Codex App Server, AGY, and Grok Build from one entrypoint |
+| Provider routing | Native connections where supported; otherwise a loopback HTTP router with provider-owned endpoint and authentication rules |
+| Protocol adaptation | Anthropic Messages, OpenAI Chat, OpenAI Responses, Ollama Chat, tool calls, thinking blocks, and SSE streams |
+| Model control | Provider catalogs, context/output limits, reasoning effort, sampling options, API-key rotation, and rate-limit handling |
+| Workspace context | Remote instructions plus atomic, workspace-scoped OKF/Markdown/JSON/YAML/TOML/text memory trees |
+| External channels | Web Chat and explicit event delivery to live terminal sessions with runtime-specific submission policies |
+| Transcript delivery | Incremental CloudEvent webhooks with durable cursors around normal turns and compaction boundaries |
+| Usage observability | Workspace SQLite ledger, authenticated events/SSE/snapshots, outbound delivery, daily audits, and legacy JSONL backfill |
+| Recovery | Invalid replay repair, repeated-tool protection, context compaction, Windows ConPTY Unicode handling, and launch-state isolation |
+
+## Runtimes and providers
+
+Ciel separates the **runtime** (the coding-agent CLI) from the **provider** (the
+model API). A runtime/provider pair can use one of three launch modes:
+
+```text
+native  -> the CLI connects directly to its supported provider endpoint
+routed  -> the CLI connects to Ciel's loopback router, which adapts the wire protocol
+router  -> Ciel runs only the local router for an external client
+```
 
-## Native and routed modes
+Dedicated adapters cover Anthropic, Ollama and Ollama Cloud, DeepSeek, OpenCode
+Zen/Go, Kimi, Z.AI, Alibaba Model Studio, xAI, OpenRouter, TaBiAI, Fireworks,
+NVIDIA NIM, vLLM, and LM Studio. A declarative catalog adds other
+OpenAI-compatible services and private gateways. The authoritative list,
+endpoint rules, and model constraints are in [Providers](docs/Providers.md).
 
-Ciel Runtime uses a provider's native endpoint when the selected agent and provider support a direct connection. Other combinations use a local HTTP router that translates request, response, streaming, thinking, and tool-call formats.
+The router binds to `127.0.0.1` by default. External access is an explicit
+debugging/operations feature and requires the configured administration token.
 
-The router binds to `127.0.0.1` by default. External router access is a debugging feature and should only be enabled on a trusted network with the external access token configured. Never expose an unauthenticated development router to the public internet.
+## Workspace context and memory
 
-Configuration is stored under `~/.config/ciel-runtime/` on macOS and Linux or `%APPDATA%\ciel-runtime\` on Windows. Override the location with `CIEL_RUNTIME_CONFIG_DIR`. Files containing credentials are written with restricted permissions where the platform supports them.
+Remote Instructions can download the native instruction file used by the
+selected CLI. Remote Memory can independently download a manifest-defined tree
+into `<workspace>/.ciel/memory` before launch.
 
-## Web Chat and MCP ownership
+- Every file is staged and validated before the prior tree is replaced.
+- Paths are constrained to the active workspace.
+- Memory pointers are projected as workspace-relative paths so projects remain portable.
+- The memory index guidance stays at the end of native and routed system context.
 
-Ciel Runtime delivers its own Web Chat and explicit wake messages. External MCP configuration, transports, subscriptions, reconnects, and lifecycle are owned by Claude Code, Codex, AGY, or the active CLI; Ciel does not discover or proxy external MCP servers.
+See [Remote Memory](docs/Remote-Memory.md) and [Configuration](docs/Configuration.md).
 
-See [docs/MCP-Channels.md](docs/MCP-Channels.md) for the ownership boundary and the stateless internal tool endpoint.
+## Events, transcripts, and usage
 
-Workspace memory trees can be synchronized from a separate HTTP manifest at
-runtime launch. Ciel downloads the declared OKF, Markdown, JSON, YAML, TOML, or
-text files atomically and appends only the local index address to the native
-runtime instruction file. See [Remote Memory](docs/Remote-Memory.md).
+Ciel's router exposes separate interfaces for inbound work and outbound
+observability:
 
-## Stable and nightly releases
+- external events and Web Chat messages can wake an active routed session;
+- transcript webhooks emit only new deltas and retain a retry cursor;
+- routed token usage is stored per workspace without prompt or credential bodies;
+- authenticated consumers can read immutable usage events, resume an SSE stream,
+  or request a time-range snapshot;
+- outbound usage delivery retries with stable event IDs and emits periodic audit snapshots.
 
-Install the stable npm release:
+Native/direct CLI traffic that bypasses the Ciel router is outside the usage
+collector's visibility. See [Usage observability](docs/usage-observability.md),
+[MCP and channels](docs/MCP-Channels.md), and the [CLI reference](docs/CLI-Reference.md).
+
+## Configuration
+
+Configuration is stored under `~/.config/ciel-runtime/` on macOS/Linux and
+`%APPDATA%\ciel-runtime\` on Windows. Workspace-owned state is isolated by the
+resolved launch workspace. Override the global configuration directory with
+`CIEL_RUNTIME_CONFIG_DIR`.
+
+Common commands:
+
+```sh
+ciel-runtimectl provider [NAME]
+ciel-runtimectl models [PROVIDER]
+ciel-runtimectl model MODEL_ID
+ciel-runtimectl status
+ciel-runtimectl remote-memory
+ciel-runtimectl transcript-events
+ciel-runtimectl usage-events
+```
+
+Use the [CLI reference](docs/CLI-Reference.md) for every command and
+[Configuration](docs/Configuration.md) for files, environment variables, and
+security boundaries.
+
+## Releases
+
+Stable releases are published from `main`:
 
 ```sh
 npm install -g @oneciel-ai/ciel-runtime@latest
 ```
 
-Install the latest nightly build:
+Nightly builds are published from `nightly` for pre-release validation:
 
 ```sh
 npm install -g @oneciel-ai/ciel-runtime@nightly
 ```
 
-Nightly builds are intended for early validation and may change behavior before the next stable release.
+See [CHANGELOG.md](CHANGELOG.md) for grouped release notes and the complete
+commit ledger included in each stable release.
+
+## Documentation
+
+| Topic | Guide |
+|---|---|
+| Install and unattended setup | [Installation](docs/Installation.md) · [Setup modes](docs/install.md) |
+| Commands and settings | [CLI reference](docs/CLI-Reference.md) · [Configuration](docs/Configuration.md) |
+| Providers and model routing | [Providers](docs/Providers.md) · [Router](docs/Router.md) |
+| Runtime design | [Architecture](docs/Architecture.md) · [Module map](docs/Module-Map.md) |
+| Memory and messaging | [Remote Memory](docs/Remote-Memory.md) · [MCP and channels](docs/MCP-Channels.md) |
+| Operations | [Observability](docs/Observability.md) · [Usage observability](docs/usage-observability.md) |
+| Verification | [Test suite](docs/Test-Suite.md) |
 
 ## Development
 
 ```sh
 npm test
 npm run lint
+npm run check:docs
 npm pack --dry-run
 ```
 
-`npm test` compiles the Python entry points and runs the complete unittest suite. The full suite includes subprocess and channel integration tests and can take several minutes.
-
-Architecture and maintenance references:
-
-- [Architecture](docs/Architecture.md)
-- [Module map](docs/Module-Map.md)
-- [Router](docs/Router.md)
-- [Configuration](docs/Configuration.md)
-- [Observability](docs/Observability.md)
-- [Test suite](docs/Test-Suite.md)
+`npm test` compiles the Python entrypoints and runs the unit, router, channel,
+and runtime test groups. CI additionally checks Python 3.10 compatibility,
+documentation links and release metadata, lint, and the npm package contents.
 
 ## Security
 
-- Keep provider API keys out of source control and shell history.
-- Keep the router bound to loopback unless remote debugging is explicitly required.
-- Treat request traces, response traces, transcripts, and event logs as potentially sensitive.
-- Review Tool Guard configuration before granting agents access to destructive tools.
+- Keep provider and consumer API keys out of source control and shell history.
+- Keep the router on loopback unless authenticated external access is required.
+- Treat traces, transcripts, event payloads, and usage metadata as sensitive.
+- Review Tool Guard policy before granting an agent destructive capabilities.
 
-Report security issues privately to the project maintainers rather than opening a public issue with credentials or request traces.
+Report security issues privately to the maintainers; do not open a public issue
+containing credentials, private prompts, or request traces.
 
 ## License
 

package/ciel-runtime-stop.cmd

@@ -3,6 +3,7 @@ setlocal
 
 set "CIEL_RUNTIME_REGISTERED_HOME="
 for /f "tokens=2,*" %%A in ('reg query HKCU\Environment /v CIEL_RUNTIME_HOME 2^>nul') do if /i "%%A"=="REG_SZ" set "CIEL_RUNTIME_REGISTERED_HOME=%%B"
+if defined CIEL_RUNTIME_REGISTERED_HOME if not exist "%CIEL_RUNTIME_REGISTERED_HOME%\ciel_runtime.py" set "CIEL_RUNTIME_REGISTERED_HOME="
 if defined CIEL_RUNTIME_HOME_OVERRIDE (
   set "CIEL_RUNTIME_SELECTED_HOME=%CIEL_RUNTIME_HOME_OVERRIDE%"
 ) else if defined CIEL_RUNTIME_REGISTERED_HOME (

package/ciel-runtime.cmd

@@ -3,6 +3,7 @@ setlocal
 
 set "CIEL_RUNTIME_REGISTERED_HOME="
 for /f "tokens=2,*" %%A in ('reg query HKCU\Environment /v CIEL_RUNTIME_HOME 2^>nul') do if /i "%%A"=="REG_SZ" set "CIEL_RUNTIME_REGISTERED_HOME=%%B"
+if defined CIEL_RUNTIME_REGISTERED_HOME if not exist "%CIEL_RUNTIME_REGISTERED_HOME%\ciel_runtime.py" set "CIEL_RUNTIME_REGISTERED_HOME="
 if defined CIEL_RUNTIME_HOME_OVERRIDE (
   set "CIEL_RUNTIME_SELECTED_HOME=%CIEL_RUNTIME_HOME_OVERRIDE%"
 ) else if defined CIEL_RUNTIME_REGISTERED_HOME (

package/ciel-runtimectl.cmd

@@ -3,6 +3,7 @@ setlocal
 
 set "CIEL_RUNTIME_REGISTERED_HOME="
 for /f "tokens=2,*" %%A in ('reg query HKCU\Environment /v CIEL_RUNTIME_HOME 2^>nul') do if /i "%%A"=="REG_SZ" set "CIEL_RUNTIME_REGISTERED_HOME=%%B"
+if defined CIEL_RUNTIME_REGISTERED_HOME if not exist "%CIEL_RUNTIME_REGISTERED_HOME%\ciel_runtime.py" set "CIEL_RUNTIME_REGISTERED_HOME="
 if defined CIEL_RUNTIME_HOME_OVERRIDE (
   set "CIEL_RUNTIME_SELECTED_HOME=%CIEL_RUNTIME_HOME_OVERRIDE%"
 ) else if defined CIEL_RUNTIME_REGISTERED_HOME (