@skein-code/cli 0.3.28 → 0.3.30

package/docs/MULTI_MODEL_TEAMS.md

@@ -152,16 +152,17 @@ The shortest setup path is the interactive user-level wizard:
 skein agents setup
 ```
 
-It asks for a connection name, provider, endpoint, credential environment
-variable, and default model. The wizard writes only the environment-variable
-name and saves shared settings under the user Skein namespace, so the same
-connection is available in every workspace. The non-interactive equivalent is
-useful for provisioning:
+It asks for a connection name, explicit relay transport, inference endpoint,
+optional model-catalog endpoint, `env` or `none` authentication, and default
+model. The wizard writes only the environment-variable name and saves shared
+settings under the user Skein namespace, so the same connection is available
+in every workspace. The non-interactive equivalent is useful for provisioning:
 
 ```bash
 skein agents setup --yes \
   --name team-relay \
   --provider compatible \
+  --protocol openai-responses \
   --base-url https://relay.example/v1 \
   --api-key-env TEAM_RELAY_API_KEY \
   --model openai/coding-model
@@ -172,25 +173,86 @@ the same next action without placing a secret in the session transcript.
 
 ### Authentication paths
 
-Skein keeps subscription login and API routing separate because they have
-different ownership and billing semantics:
+Skein keeps primary relay routing and delegated CLI login separate because they
+have different ownership and billing semantics:
 
 - Subscription users authenticate once in each installed official CLI. Codex
   supports ChatGPT subscription login, Claude Code supports Claude.ai/Teams
   login, and Gemini CLI supports Google account login. A Skein route with
   `runtime: "codex"`, `"claude"`, or `"grok"` reuses that CLI's local login;
   Skein does not read, copy, or persist its tokens.
-- Direct API users reference the provider's environment variable on each
-  route, or let a compatible parent route inherit the same endpoint.
+- Existing direct API routes remain readable for backward compatibility; they
+  are not the evolution path for new primary connections.
 - Relay/gateway users define one named `connection` and reuse it across model
-  routes. This matches gateways such as OpenRouter or LiteLLM that expose many
-  models behind one OpenAI-compatible endpoint and bearer key.
+  routes. This matches gateways such as OpenRouter, LiteLLM, and Vercel AI
+  Gateway that expose Responses, Chat Completions, and/or Anthropic Messages
+  behind one relay credential.
+
+### Primary model connection selection
+
+The primary agent and team routes share the same connection catalog. User
+configuration under `agents.connections` is merged with strict named
+environment profiles:
+
+```bash
+export SKEIN_CONNECTIONS=work,local
+export SKEIN_CONNECTION_WORK_PROVIDER=compatible
+export SKEIN_CONNECTION_WORK_PROTOCOL=openai-responses
+export SKEIN_CONNECTION_WORK_BASE_URL=https://relay.example/v1
+export SKEIN_CONNECTION_WORK_API_KEY_ENV=WORK_RELAY_KEY
+export SKEIN_CONNECTION_WORK_MODEL=coder
+export SKEIN_CONNECTION_LOCAL_PROVIDER=compatible
+export SKEIN_CONNECTION_LOCAL_PROTOCOL=openai-chat
+export SKEIN_CONNECTION_LOCAL_BASE_URL=http://127.0.0.1:11434/v1
+export SKEIN_CONNECTION_LOCAL_AUTH=none
+```
+
+IDs are lowercase shell-safe names. IDs that collide after environment
+normalization (for example `team-a` and `team_a`) are rejected. Endpoint and
+credential fields never cross profile boundaries. Selection precedence is an
+explicit `--connection`, the configured default, then automatic selection only
+when exactly one complete profile exists. Multiple complete profiles open a
+TTY selector; headless runs fail with `Pass --connection <name>`.
+
+New named connections are relay-only: `provider` is `compatible`, authentication
+is exactly `env` or `none`, and the transport is `openai-responses`,
+`openai-chat`, or `anthropic-messages`. OAuth, keychain, command helpers, and
+official account login are not connection schema variants. Custom legacy native
+provider endpoints do not inherit the provider's official API key.
+
+Responses is the default because OpenAI recommends it for new projects. Skein
+sets `store: false` and replays the complete returned output items plus tool
+outputs on the next request, which also works with stateless relay
+implementations. Protocol failures never trigger an automatic request through a
+different transport, avoiding duplicate inference and billing.
+
+Some relays publish two SDK base URLs for the same account. The OpenAI base
+usually includes `/v1`; the Anthropic base may be a root or provider prefix and
+expects the client to append `/v1/messages`. This is why inference `baseUrl` and
+OpenAI-style `modelsBaseUrl` are distinct. An Anthropic transport must configure
+`modelsBaseUrl` explicitly:
+
+```json
+{
+  "provider": "compatible",
+  "protocol": "anthropic-messages",
+  "baseUrl": "https://relay.example/anthropic",
+  "modelsBaseUrl": "https://relay.example/v1",
+  "defaultModel": "anthropic/coding-model",
+  "auth": {"type": "env", "name": "TEAM_RELAY_API_KEY"}
+}
+```
 
 Official authentication references: [Codex](https://developers.openai.com/codex/auth),
 [Claude Code](https://code.claude.com/docs/en/authentication), and
 [Gemini CLI](https://geminicli.com/docs/get-started/authentication/). Unified
 gateway examples: [OpenRouter](https://openrouter.ai/docs/quickstart) and
 [LiteLLM](https://docs.litellm.ai/docs/learn/gateway_quickstart).
+Transport references: [OpenAI Responses migration](https://developers.openai.com/api/docs/guides/migrate-to-responses),
+[OpenRouter Responses](https://openrouter.ai/docs/api/reference/responses/overview),
+[OpenRouter Anthropic Messages](https://openrouter.ai/docs/api/api-reference/anthropic-messages/create-a-message),
+[LiteLLM supported endpoints](https://docs.litellm.ai/docs/supported_endpoints),
+and [Vercel AI Gateway APIs](https://vercel.com/docs/ai-gateway/sdks-and-apis).
 
 ```json
 {
@@ -247,8 +309,10 @@ role. Add a profile entry only when that role needs a different model:
     "connections": {
       "team-relay": {
         "provider": "compatible",
+        "protocol": "openai-responses",
         "baseUrl": "https://relay.example/v1",
-        "apiKeyEnv": "TEAM_RELAY_API_KEY"
+        "defaultModel": "openai/coding-model",
+        "auth": {"type": "env", "name": "TEAM_RELAY_API_KEY"}
       }
     },
     "routes": {
@@ -268,8 +332,9 @@ need different connections:
     "connections": {
       "team-relay": {
         "provider": "compatible",
+        "protocol": "openai-responses",
         "baseUrl": "https://relay.example/v1",
-        "apiKeyEnv": "TEAM_RELAY_API_KEY"
+        "auth": {"type": "env", "name": "TEAM_RELAY_API_KEY"}
       }
     },
     "routes": {
@@ -295,16 +360,25 @@ need different connections:
 ```
 
 Run `skein agents connections` or `/connections` to inspect the resolved
-endpoint, environment-variable reference, and route count without revealing
-the key. For compatible/OpenAI connections, run
-`skein agents models team-relay` to inspect the provider's `/models` catalog
-before choosing route IDs. Discovery is read-only and does not rewrite config;
-native Anthropic/Gemini subscription catalogs remain owned by their official
-CLIs. Named connections are best kept in user-level configuration. A
+inference endpoint, model-catalog endpoint, environment-variable reference,
+and route count without revealing the key. Run `skein agents models
+team-relay` to inspect the relay's OpenAI-style `/models` catalog before
+choosing route IDs. Discovery is read-only and does not rewrite config. Its
+process-local cache is bounded to 32 endpoint/auth fingerprints with a 15-minute
+TTL and ETag revalidation; secret values are hashed into the in-memory
+fingerprint and never cached. `401`/`403` invalidates the entry and never returns
+stale models as an authentication success. Named connections are best kept in
+user-level configuration. A
 repository-owned connection or route remains disabled until the project config
 is explicitly trusted, preventing a cloned repository from redirecting a
 developer's key and source context to an attacker-controlled endpoint.
 
+External CLI runtimes remain separate from native connections. Skein launches
+them with a minimal environment containing only the safe executable path,
+home/temporary/locale facts, and that runtime's own config directory. Provider
+keys, `SKEIN_*` credentials, unrelated connection keys, and `NODE_OPTIONS` are
+not inherited by the child process.
+
 Routing precedence is explicit and predictable: a profile route overrides team
 defaults; a route that specifies `provider` without `connection` bypasses the
 default connection; otherwise the current parent model is used when no team

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.28`.
+- Current repository version: `0.3.30`.
 - 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).
@@ -24,7 +24,8 @@ one of the milestones below.
   all sizes support prompt
   history, `@file` completion, command completion, multiline editing, queued
   follow-ups, live context inspection, permission approval, themes, ASCII mode,
-  `NO_COLOR`, and narrow-height degradation.
+  `NO_COLOR`, `TERM=dumb`, screen-reader output, reduced motion, and
+  narrow-height degradation.
 - Storage: sessions, checkpoints, local index, and project configuration still
   use `.mosaic/` paths for compatibility. `SKEIN_*` environment variables are
   preferred, while `MOSAIC_*` aliases remain supported.
@@ -41,16 +42,19 @@ npm audit --omit=dev
 npm run release:verify -- --output-dir artifacts/package
 ```
 
-The latest verified package is `skein-code-cli-0.3.28.tgz`. The verifier writes
-its SHA-256 to `artifacts/package/skein-code-cli-0.3.28.tgz.sha256`, and CI
+The latest verified package is `skein-code-cli-0.3.30.tgz`. The verifier writes
+its SHA-256 to `artifacts/package/skein-code-cli-0.3.30.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.
 
-The final verification included a fresh install for all three executable
-aliases. PTY coverage included 20, 24 ASCII, 40, 80, 120 columns and a 40x10
-short-height case. The current full-suite count is recorded from the latest
-`npm run check` in the release evidence.
+The final verification includes a fresh install for all three executable
+aliases. PTY coverage includes 20, 24 ASCII/`NO_COLOR`, 40, 80, and 120 columns;
+a 40x10 short-height case; 40-column `TERM=dumb`; and 80-column screen-reader
+interaction. Raw output is replayed through a headless terminal so the gate
+checks the final visible screen rather than only accumulated logs. The current
+full-suite count is recorded from the latest `npm run check` in the release
+evidence.
 
 ## Recommended Order
 
@@ -366,25 +370,43 @@ Implementation progress:
   stopped attempt in telemetry, and feeds only the fresh result into the
   caller's aggregation. Completed attempts remain immutable until the next
   report-inspection increment.
-- Named `agents.connections` now let API routes share one provider, base URL,
-  and credential environment-variable reference. This supports the common
-  relay/gateway case where one key grants access to many model families while
-  keeping subscription-backed official CLIs on their own login path.
+- Named `agents.connections` and `SKEIN_CONNECTION_*` profiles now let the
+  primary agent and API routes share one provider, protocol, base URL, default
+  model, and typed authentication reference. One complete connection is
+  selected automatically; multiple candidates require a TTY choice or
+  `--connection` in headless mode. New connections are relay-only and accept
+  only `env` or `none`; subscription-backed official CLIs remain isolated
+  delegated runtimes rather than primary connections.
 - `skein agents connections` and `/connections` expose redacted connection
   status and route counts. Repository-owned connections are stripped until
   project config is trusted, just like direct model routes.
-- `skein agents models <connection>` can query a compatible/OpenAI connection's
-  standard `/models` endpoint, giving users model IDs without trial-and-error
-  configuration. The command is read-only and does not persist the catalog.
+- `skein agents models <connection>` queries the relay's independent
+  OpenAI-style `/models` endpoint. A 32-entry process-local cache uses a
+  15-minute TTL, ETag revalidation, endpoint/credential fingerprint isolation,
+  and hard invalidation on `401`/`403`; it never stores credential values or
+  treats stale data as an authentication success.
 - Team routing now supports `agents.defaultConnection` and optional
   `agents.defaultModel`. Most users configure one shared gateway once; profile
   routes only contain model or provider overrides when needed. CLI and TUI
   surfaces label inherited versus overridden routes, and unknown defaults fail
   validation before any agent starts.
 - `skein agents setup` now provides a guided user-level setup for a shared
-  connection and default model, with a non-interactive provisioning form. The
-  wizard stores only credential environment-variable names and preserves other
-  user configuration.
+  connection and default model, with explicit Responses, Chat Completions, and
+  Anthropic Messages transports plus separate inference/model-catalog bases.
+  The first-run TUI uses the same relay-only model and stores only credential
+  environment-variable names while preserving other user configuration.
+- The Responses transport uses `POST /responses`, `store: false`, typed SSE,
+  normalized text/function/usage events, and exact output-item replay for
+  stateless tool and reasoning continuation. It never retries a failed request
+  through a different protocol. Anthropic relay transport accepts SDK-style
+  root bases, appends `/v1/messages` when needed, and uses relay bearer auth.
+- `skein doctor` reports unsupported `SEKIN_API`/`SKEIN_BASEURL` spellings and
+  connection readiness without reading or printing their values. Custom native
+  endpoints cannot inherit official provider keys, and external CLI runtimes
+  receive a minimal environment allowlist instead of the parent secret set.
+- This relay-only connection catalog, Responses transport, independent model
+  directory, redacted status, and delegated-runtime isolation slice is complete
+  and release-verified in `0.3.30`.
 - Team budgets default to `observe`: telemetry is retained, but configured
   thresholds do not warn or terminate work. `guard` adds non-blocking threshold
   warnings, while `strict` is an explicit hard-stop policy for controlled jobs.
@@ -462,14 +484,19 @@ already separated short-term working memory and durable records:
 Never promote model-inferred facts directly into durable memory without the
 existing candidate/approval path.
 
-### P2: Terminal Accessibility And Visual Regression
-
-Keep the current restrained graphite/cinder/mono theme system and add actual
-final-frame regression tests for widths 20-160 and heights 8-60. Include CJK,
-wide emoji, screen-reader mode, `TERM=dumb`, `NO_COLOR`, ASCII glyph mode,
-permission panels, multiline composer, history search, and active palettes.
-Use a terminal emulator fixture where raw ANSI logs cannot prove what remains
-visible in the final frame.
+### P2: Terminal Accessibility And Visual Regression (complete in 0.3.29)
+
+Version `0.3.29` adds an explicit screen-reader profile, automatic `TERM=dumb`
+fallback, semantic Ink roles, reduced motion, and non-incremental low-capability
+rendering. The PTY release gate now covers the contracted 20/24/40/80/120-column
+matrix, 40x10 height constraint, CJK/emoji component fixtures, ASCII,
+`NO_COLOR`, permission/error/ready states, history search, and file completion.
+It replays logs through `@xterm/headless` and rejects final-frame wraps, stale
+panels, control-probe leaks, joined announcements, or missing status. The
+single-process benchmark enforces 25 ms input and 150 ms streaming-render p95
+budgets while requiring the last chunk in the final frame. Future expansion may
+sample additional widths through 160 and heights through 60 without changing
+the shipped gate's factual scope.
 
 ### P3: Distribution
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skein-code/cli",
-  "version": "0.3.28",
+  "version": "0.3.30",
   "description": "A context-first, model-agnostic coding agent with an auditable terminal workspace.",
   "type": "module",
   "license": "MIT",
@@ -16,6 +16,17 @@
   },
   "skein": {
     "releaseNotes": [
+      "Named primary connections now target third-party compatible relays only, use explicit env or none authentication, and resolve one complete profile automatically while requiring an explicit choice for ambiguity",
+      "OpenAI Responses is the recommended new transport with POST /responses, store false, typed SSE, normalized tools and usage, and bounded exact output-item replay for stateless reasoning continuation",
+      "OpenAI Chat Completions and Anthropic Messages remain explicit relay transports without cross-protocol retries; inference and OpenAI-style model catalog base URLs are configured independently",
+      "Relay model discovery now uses a bounded 15-minute ETag cache isolated by endpoint and credential fingerprints, invalidates authentication failures, and never stores or echoes credential values",
+      "First-run and agents setup flows are relay-only, save only credential environment-variable names, and expose redacted connection state consistently across TUI, text, JSON, JSONL, doctor, and config output",
+      "Provider diagnostics redact secrets, authorization headers, URL credentials, and query strings while Responses replay state is capped at 128 items and 4 MiB in memory and persisted sessions",
+      "External delegated CLIs now receive a minimal runtime-owned environment instead of inheriting provider, Skein, relay, or NODE_OPTIONS secrets",
+      "TERM=dumb and screen-reader sessions now use deterministic ASCII, monochrome, reduced-motion, non-incremental rendering without losing keyboard input",
+      "SKEIN_SCREEN_READER=1 enables Ink accessibility output with semantic timeline, permission, and composer roles plus clean phase boundaries",
+      "PTY release gates now replay eight terminal scenarios through a headless emulator and reject final-frame overflow, stale panels, announcement joins, and missing status",
+      "A local terminal UI benchmark enforces 25 ms input and 150 ms streaming-render p95 budgets while retaining the final streamed chunk",
       "MCP trust and revoke confirmation rendering now has a deterministic cross-platform release regression gate",
       "MCP now follows a no-network search and inspect review before explicit workspace-bound manifest trust and lazy activation",
       "Declarative capability manifests expose redacted source, version, tools, permissions, network, command, path, sensitive-field, process, and completion-evidence effects",
@@ -99,6 +110,7 @@
     "benchmark:context": "tsx scripts/benchmark-local-index.ts",
     "benchmark:duplication": "tsx scripts/benchmark-duplication.ts",
     "benchmark:token-economy": "tsx scripts/benchmark-token-economy.ts",
+    "benchmark:terminal-ui": "tsx scripts/benchmark-terminal-ui.ts",
     "verify:package": "node scripts/verify-package.mjs",
     "release:verify": "npm run check && npm run verify:package --",
     "typecheck": "tsc --noEmit",
@@ -126,6 +138,7 @@
     "@types/diff": "^8.0.0",
     "@types/node": "^22.19.7",
     "@types/react": "^19.2.7",
+    "@xterm/headless": "^6.0.0",
     "tsup": "^8.5.1",
     "tsx": "^4.21.0",
     "vitest": "^4.0.18"