@skein-code/cli 0.3.29 → 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.29`.
+- 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).
@@ -42,8 +42,8 @@ npm audit --omit=dev
 npm run release:verify -- --output-dir artifacts/package
 ```
 
-The latest verified package is `skein-code-cli-0.3.29.tgz`. The verifier writes
-its SHA-256 to `artifacts/package/skein-code-cli-0.3.29.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.
@@ -370,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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skein-code/cli",
-  "version": "0.3.29",
+  "version": "0.3.30",
   "description": "A context-first, model-agnostic coding agent with an auditable terminal workspace.",
   "type": "module",
   "license": "MIT",
@@ -16,6 +16,13 @@
   },
   "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",