@skein-code/cli 0.3.21 → 0.3.23

package/docs/ARCHITECTURE.md

@@ -268,13 +268,18 @@ JavaScript plugins are intentionally unsupported because they would share the
 CLI's full filesystem, environment, and process privileges.
 
 MCP is the interoperability boundary for external executable capabilities. It
-is disabled by default, removed from untrusted project configuration, exposes
-namespaced tools, treats server annotations as untrusted, and applies argument,
-schema, result, server-count, timeout, and transport limits. Every MCP call
-currently requires the network permission category. A configured stdio server
-is still an external program with the user's operating-system privileges; cwd
-and environment validation reduce accidental exposure but are not a sandbox.
-Only reviewed user-owned configuration should enable one.
+is disabled by default, removed from untrusted project configuration, exposes a
+compact lazy activation catalog during normal chat startup, treats server
+annotations as untrusted, and applies argument, schema, result, server-count,
+timeout, and transport limits. The `mcp_activate` catalog connects a selected
+server on demand, discovers its remote tools, and registers at most eight
+request-relevant schemas into the live registry; explicit diagnostic commands
+such as `skein mcp status` can still connect all configured servers eagerly.
+Every MCP activation and remote MCP call currently requires the network
+permission category. A configured stdio server is still an external program
+with the user's operating-system privileges; cwd and environment validation
+reduce accidental exposure but are not a sandbox. Only reviewed user-owned
+configuration should enable one.
 
 Before any marketplace-style plugin support, add a declarative capability
 manifest, first-run review, lazy tool-schema activation, per-server permission

package/docs/NEXT_STEPS.md

@@ -9,7 +9,7 @@ one of the milestones below.
 
 - Product name: `Skein`; primary executable: `skein`.
 - Compatibility executables: `mosaic` and `mosaic-code`.
-- Current repository version: `0.3.21`.
+- Current repository version: `0.3.23`.
 - Runtime requirement: Node.js `>=22.16.0` (the runtime uses unflagged
   `node:sqlite` with FTS5, and current CLI/build dependencies require this
   Node 22 baseline).
@@ -41,8 +41,8 @@ npm audit --omit=dev
 npm run release:verify -- --output-dir artifacts/package
 ```
 
-The latest verified package is `skein-code-cli-0.3.21.tgz`. The verifier writes
-its SHA-256 to `artifacts/package/skein-code-cli-0.3.21.tgz.sha256`, and CI
+The latest verified package is `skein-code-cli-0.3.23.tgz`. The verifier writes
+its SHA-256 to `artifacts/package/skein-code-cli-0.3.23.tgz.sha256`, and CI
 retains the checksum beside the package metadata. The checksum is deliberately
 not copied into this packaged document because doing so would change the
 archive it describes.
@@ -99,14 +99,30 @@ firewall policies while requiring complete evidence and recovery coverage.
 The replay reports a 36.7% estimated-input reduction; this is a deterministic
 budget measurement, not a provider billing or task-success claim.
 
-MCP tool definitions are now marked for progressive disclosure. Catalogs of
-eight or fewer eligible tools remain fully visible; larger catalogs disclose a
-deterministically ranked maximum of eight schemas. Selected schemas retain
-their registry order and remain loaded for the current run, and Token Ledger
-receipts record the deferred count. MCP tools remain `network` operations and
-hidden tool calls remain rejected by the existing boundary. This release does
-not defer MCP connection or remote `listTools` discovery and does not claim the
-provider-cache or Context Compaction 2.0 follow-up work is complete.
+MCP tool definitions are now marked for progressive disclosure. Normal chat
+startup exposes a compact `mcp_activate` catalog instead of connecting every
+server. Selecting a configured server connects it, runs remote `listTools`, and
+loads at most eight request-relevant schemas into the live registry. Selected
+schemas retain their registry order and remain loaded for the current run, and
+Token Ledger receipts record the deferred count. MCP activation and discovered
+tools remain `network` operations, hidden tool calls remain rejected by the
+existing boundary, and explicit diagnostics such as `skein mcp status` still
+connect eagerly by design.
+
+Version `0.3.22` normalizes provider-reported cache and reasoning usage across
+streaming and non-streaming OpenAI, Anthropic, and Gemini responses. Token
+Ledger receipts, cumulative session usage, and JSON/JSONL events retain cached
+input, cache-write input, and reasoning counts when present, including explicit
+zero values. The session schema remains compatible with older records. This is
+measurement plumbing only: it does not enable provider cache controls, define a
+stable cache key, defer MCP connection/discovery, run paid same-model task A/B,
+or complete Context Compaction 2.0.
+
+Version `0.3.23` completes the true lazy MCP lifecycle slice: normal chat
+startup performs zero MCP transport connections and zero remote discovery until
+the model explicitly calls `mcp_activate` for a configured server. The release
+does not add per-server trust scopes, provider billing A/B, or Context
+Compaction 2.0.
 
 ### P0-D: Repository reuse and calibrated duplication enforcement
 
@@ -355,10 +371,11 @@ Add a first-run catalog and inspection flow for bundled capabilities. Keep
 installation explicit and reviewable: show source, requested tools, filesystem
 scope, network scope, and trust state before activation. Add fixture servers and
 Skills that exercise timeout, malformed schema, disconnect, and version drift.
-Introduce lazy MCP schema discovery and declarative capability manifests before
-any marketplace. Do not load arbitrary plugin JavaScript in-process; package
-reusable extensions as data-only Skills/workflows plus explicitly trusted MCP
-servers, with an optional subprocess sandbox for stdio servers.
+Lazy MCP activation is now the default chat path. Next, add declarative
+capability manifests, per-server trust review, activation telemetry, and an
+optional subprocess sandbox before any marketplace. Do not load arbitrary plugin
+JavaScript in-process; package reusable extensions as data-only Skills/workflows
+plus explicitly trusted MCP servers.
 
 ### P2: Memory Quality And User Control
 

package/docs/PRODUCT_BENCHMARK.md

@@ -20,7 +20,7 @@ product surfaces.
 
 | Area | Mainstream signal | Skein today | Product implication |
 | --- | --- | --- | --- |
-| Context | Auggie automatically indexes projects and offers context-aware interactive and print modes. Its MCP Tool Search avoids loading every remote schema up front. See [Auggie overview](https://docs.augmentcode.com/cli/overview) and [integrations](https://docs.augmentcode.com/cli/integrations). | Local BM25/path/symbol retrieval with language-aware chunks, current-file freshness checks, diversity-aware token packing, progressive Skills, and hard token caps. MCP schemas are registered eagerly. | Benchmark local recall and latency by language, then make MCP tool discovery lazy and measurable. |
+| Context | Auggie automatically indexes projects and offers context-aware interactive and print modes. Its MCP Tool Search avoids loading every remote schema up front. See [Auggie overview](https://docs.augmentcode.com/cli/overview) and [integrations](https://docs.augmentcode.com/cli/integrations). | Local BM25/path/symbol retrieval with language-aware chunks, current-file freshness checks, diversity-aware token packing, progressive Skills, and hard token caps. Normal chat startup exposes only a compact `mcp_activate` server catalog; remote MCP connection, `listTools`, and up to eight relevant schemas are loaded on demand. | Measure lazy MCP activation cost and add per-server trust review/sandboxing before marketplace-style plugin support. |
 | Tool result economy | FastCtx argues for structured file/search tools, explicit pagination, bounded output tiers, and persistent background-job logs so the model spends fewer turns on shell mechanics. See the [FastCtx repository](https://github.com/yc-duan/fastctx) and its [LINUX DO introduction](https://linux.do/t/topic/2612425). These are design signals, not independent evidence that every model becomes more accurate. | Native tools already use closed schemas and permission/checkpoint boundaries. Oversized results now use a dynamic token budget, head/tail receipts, source-truncation telemetry, and redacted session-scoped local readback. Single-file UTF-8 reads and foreground-only shell execution remain narrower than FastCtx. | Keep FastCtx optional through MCP instead of duplicating the default kernel. Add measured read/list/search continuation and batch reading before considering persistent background jobs. |
 | Workflow modes | Claude Code documents isolated subagents, agent teams, hooks, code intelligence, Skills, MCP, and plugins in one extension model. See [Claude Code extensions](https://code.claude.com/docs/en/features-overview). Copilot CLI exposes Plan and Autopilot modes. See [Copilot CLI](https://github.com/features/copilot/cli). | Ask and Build modes exist; Ask is read-only but does not produce a named approval-ready plan. | Add an explicit Plan mode. Keep it read-only and require approval before Build. |
 | Code intelligence | Claude Code advertises language-server-backed symbol navigation and live type errors. | Retrieval is lexical/BM25/path/symbol index based; no LSP diagnostics or rename graph. | Add an optional LSP adapter after storage and scheduler foundations. |
@@ -43,8 +43,9 @@ product surfaces.
    quarantining the canonical copy; `--recover` handles interrupted operations;
    `--home` covers user-level state. Shared leases cover live managed writers,
    while namespace mutation requires an exclusive crash-released lease.
-4. **P1 MCP progressive disclosure:** search and activate remote tool schemas
-   on demand instead of placing every schema in every model request.
+4. **P1 MCP trust hardening:** add per-server review, capability manifests,
+   activation telemetry, and optional stdio sandboxing on top of lazy MCP
+   activation.
 5. **P1 scheduler and isolation:** retain the shipped task-budget telemetry and
    reviewer loop, then add cancellation propagation, deterministic integration,
    and single-writer/worktree boundaries.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skein-code/cli",
-  "version": "0.3.21",
+  "version": "0.3.23",
   "description": "A context-first, model-agnostic coding agent with an auditable terminal workspace.",
   "type": "module",
   "license": "MIT",
@@ -16,6 +16,12 @@
   },
   "skein": {
     "releaseNotes": [
+      "Normal chat startup now exposes a compact mcp_activate catalog instead of eagerly connecting MCP servers",
+      "MCP activation connects one selected server, discovers remote tools, and loads at most eight relevant schemas",
+      "Explicit MCP diagnostics can still connect eagerly while all MCP activation and remote calls remain network operations",
+      "OpenAI, Anthropic, and Gemini usage now normalizes cached input, cache-write input, and reasoning tokens when reported",
+      "Token Ledger, session totals, and structured usage events preserve provider cache and reasoning counts without prompt content",
+      "Streaming, non-streaming, explicit-zero, and legacy-session compatibility paths are covered without claiming cache activation",
       "Failed configured verification output yields bounded current-run diagnostic ranking without persisting paths",
       "Diagnostic hints cannot create zero-relevance hits and are cleared on success or the next agent run",
       "Python absolute and relative module imports now contribute deterministic offline graph adjacency",