@leanandmean/coding-agent 0.74.1-scramjet.70 → 0.74.1-scramjet.71

package/docs/json.md

@@ -6,6 +6,12 @@ scramjet --mode json "Your prompt"
 
 Outputs all session events as JSON lines to stdout. Useful for integrating Scramjet into other tools or custom UIs.
 
+## Invocation-scoped models and failures
+
+`--mode json` accepts `--model-definition '<JSON>'` or `--model-definition-env NAME` for a process-local compatible route. See [the complete contract](models.md#invocation-scoped-headless-models) for required deployment-evidenced limits, strict environment credentials, conflicts and persistence. The definition is not automatically activated by ambient environment variables.
+
+Invalid definition/environment input fails startup with nonzero status. Generation failures may still exit zero in JSON mode: inspect finalized assistant `message_end` entries for `stopReason: "error"`/`"aborted"`, their `errorMessage`/diagnostics, and retry outcomes rather than treating process exit or `agent_end` as success. Explicit request failures do not silently switch routes; existing same-route recovery remains. Text print errors retain nonzero status; [RPC](rpc.md) separately distinguishes prompt acceptance from generation success. No new event shape or exit policy is introduced.
+
 ## Event Types
 
 Events are defined in [`AgentSessionEvent`](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/agent-session.ts#L102):

package/docs/models.md

@@ -4,6 +4,7 @@ Add custom providers and models (Ollama, vLLM, LM Studio, proxies) via `~/.scram
 
 ## Table of Contents
 
+- [Invocation-scoped Headless Models](#invocation-scoped-headless-models)
 - [Minimal Example](#minimal-example)
 - [Full Example](#full-example)
 - [Supported APIs](#supported-apis)
@@ -14,6 +15,72 @@ Add custom providers and models (Ollama, vLLM, LM Studio, proxies) via `~/.scram
 - [Anthropic Messages Compatibility](#anthropic-messages-compatibility)
 - [OpenAI Compatibility](#openai-compatibility)
 
+## Invocation-scoped Headless Models
+
+Use one model definition for a single headless invocation without editing `models.json` or installing an extension:
+
+- `--model-definition '<JSON>'` supplies strict JSON directly.
+- `--model-definition-env NAME` reads strict JSON from the named environment variable only when explicitly selected.
+
+Both selectors accept `=value` forms. Missing values, repeated selectors, using both selectors, or combining either with `--provider`, `--model`, `--models` or `--api-key` are errors. Ambient definition variables alone never activate a route. Use `--thinking` separately: the model `id` is a nonblank literal backend ID, preserving case, slashes and colons without fuzzy matching, provider-prefix parsing or thinking-suffix interpretation.
+
+Supported execution modes are `--print`, `--mode json`, `--mode rpc`, and print mode selected by redirected stdin. Actual interactive execution is rejected. Help/version need no credentials; `--list-models` can inspect a supplied definition without resolving its credential.
+
+### Definition fields
+
+| Field | Requirement and meaning |
+|-------|-------------------------|
+| `api` | Required: `openai-completions`, `openai-responses`, `anthropic-messages`, or `google-generative-ai` |
+| `baseUrl` | Required absolute HTTP(S) URL with a host; no userinfo, query, fragment, controls or whitespace. Supply the adapter-appropriate base path; there is no endpoint/version discovery. |
+| `id` | Required nonblank literal backend model ID |
+| `apiKeyEnv` | Required environment variable identifier containing a nonblank credential at startup |
+| `contextWindow` | Required positive finite maximum supported total context; positive fractional values remain accepted |
+| `maxTokens` | Required positive safe-integer maximum output allowance |
+| `name` | Optional nonempty label; defaults to `id` |
+| `reasoning` | Optional boolean; defaults to `false` |
+| `input` | Optional array of `text`/`image` modalities; defaults to `["text"]` |
+| `thinkingLevelMap` | Optional existing [thinking-level mapping](#thinking-level-map) |
+| `compat` | Optional existing API-valid [OpenAI](#openai-compatibility) or [Anthropic](#anthropic-messages-compatibility) compatibility overrides; API-incompatible fields are rejected |
+| `cost` | Optional complete finite-number `input`, `output`, `cacheRead`, `cacheWrite` estimates per million tokens; defaults to zero estimates |
+| `maxInputTokens` | Optional positive finite independent input constraint, evidenced for the supplied route |
+| `requestLimits` | Optional nonempty array of existing [joint endpoint constraints](#joint-endpoint-constraints) |
+
+Unknown fields, including nested unsupported keys/values, are rejected. Credential literals, headers, provider identity, OAuth, custom stream functions, provider collections/overrides, file references and discovery configuration are not supported. JSON comments and trailing commas are rejected; input is never loaded from a file or evaluated as a shell command.
+
+Obtain limits and capabilities from the actual deployment's applicable documentation/account metadata. `contextWindow` stays the total-context denominator; input constraints and output allocation remain separate. Output need not be less than total context: existing request-local allocation bounds feasible output without changing either scalar maximum. These estimates/checks do not establish backend acceptance, entitlement or exact serialized token counts. Omitted capabilities are client defaults, not capability evidence; zero cost estimates do not mean free billing. Existing adapter compatibility defaults still apply.
+
+### Example using caller deployment metadata
+
+For a deployment confirmed to implement Chat Completions, set `DEPLOYMENT_BASE_URL`, `DEPLOYMENT_MODEL_ID`, `DEPLOYMENT_CONTEXT_WINDOW` and `DEPLOYMENT_MAX_OUTPUT` from its metadata, and export `ROUTE_API_KEY` from your credential source. Then, using `jq` to construct JSON:
+
+```sh
+export ROUTE_DEFINITION="$(jq -n \
+  --arg baseUrl "$DEPLOYMENT_BASE_URL" \
+  --arg id "$DEPLOYMENT_MODEL_ID" \
+  --argjson contextWindow "$DEPLOYMENT_CONTEXT_WINDOW" \
+  --argjson maxTokens "$DEPLOYMENT_MAX_OUTPUT" \
+  '{api:"openai-completions",baseUrl:$baseUrl,id:$id,apiKeyEnv:"ROUTE_API_KEY",contextWindow:$contextWindow,maxTokens:$maxTokens}')"
+scramjet --print --model-definition-env ROUTE_DEFINITION "Summarize this project"
+# Equivalent inline selector, without putting the credential in JSON:
+scramjet --mode json --model-definition "$ROUTE_DEFINITION" "Summarize this project"
+```
+
+Both environment names must be valid identifiers with nonblank values. The credential is captured once, preserving its bytes; it is never interpreted as a shell command, second variable name or literal fallback. Missing credentials fail startup instead of borrowing saved/provider credentials. For an unauthenticated server, the caller may supply a nonblank placeholder in the named credential variable; Scramjet does not invent one. Definition metadata, including the URL, is nonsecret and normally visible through RPC/model output. Controlled input errors omit raw JSON, rejected URL contents and credential values; arbitrary remote echoes and trusted extensions are not covered by a universal redaction guarantee.
+
+### Lifetime, selection and persistence
+
+Each invocation registers a fresh non-vendor `invocation-<UUID>` provider identity in memory and selects its exact model, bypassing saved startup defaults and scopes. Discover this generated identity through RPC `get_state`/`get_available_models`; concurrent invocations using the same backend ID remain independent. Credentials stay in runtime auth overrides, not model metadata or configuration.
+
+Refresh/reload retain the registration. Replacement registries re-register the same captured definition/key. `new_session` inherits the live model/thinking after a deliberate switch; non-inherited session switch/fork/import selection uses the supplied definition. Explicit later model switching remains allowed: this is not a route lock or protection against arbitrary trusted extensions. No automatic forwarding of the complete route to subagents is provided.
+
+All sessions created by a definition invocation opt out of saving model/thinking defaults, including later setters/cycling, replacements and switches to other models. Live state, events and ordinary journal model/thinking entries still change. Auth/model configuration remains unchanged; unrelated settings, journals and observational files may still be written. Use `--no-session` to disable journal saving, not as a general filesystem sandbox.
+
+Endpoints/keys/limits are not revived from journal model identity. Resupply the definition in each fresh process. Reopening without selectors uses ordinary unavailable-model restoration warnings and default/available-model fallback; it is **not** fail-closed ordinary resume. An explicit invocation startup records its effective branch-local model/thinking identity using existing journal shapes.
+
+Invalid definition/environment input fails before migrations/runtime construction with nonzero status. Explicit registration or request failures do not silently select a substitute route; existing retries/compaction may retry the same selected route. Text generation failures report errors and nonzero status. JSON generation errors can accompany exit zero: inspect finalized assistant error events. RPC prompt acceptance is not generation success: inspect subsequent events. See [JSON](json.md), [RPC](rpc.md) and [SDK preference persistence](sdk.md#model-preference-persistence).
+
+`google-generative-ai` explicitly pins the generic API even when `GOOGLE_GENAI_USE_VERTEXAI` or `GOOGLE_GENAI_USE_ENTERPRISE` is set. This also applies to configured/dynamic models and direct generic AI streams. Vertex routing requires the existing explicit `google-vertex` API/configuration, which is outside invocation-definition support. Compatibility with every enterprise endpoint is not established; ambient cloud flags are not a supported migration mechanism.
+
 ## Minimal Example
 
 For local models (Ollama, LM Studio, vLLM), only `id` is required per model:
@@ -237,13 +304,13 @@ Current behavior:
 
 ### Thinking Level Map
 
-Use `thinkingLevelMap` on a model to describe model-specific thinking controls. Keys are scramjet thinking levels: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`.
+Use `thinkingLevelMap` on a model to describe model-specific thinking controls. Keys are scramjet thinking levels: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`.
 
 Values are tristate:
 
 | Value | Meaning |
 |-------|---------|
-| omitted | Level is supported and uses the provider's default mapping |
+| omitted | Ordinary levels use the provider's default mapping; `xhigh` and `max` require explicit string mappings to be supported |
 | string | Level is supported and this value is sent to the provider |
 | `null` | Level is unsupported and hidden/skipped/clamped away |
 

package/docs/rpc.md

@@ -16,6 +16,14 @@ Common options:
 - `--no-session`: Disable session persistence
 - `--session-dir <path>`: Custom session storage directory
 
+### Invocation-scoped model startup
+
+Start with `scramjet --mode rpc --model-definition-env ROUTE_DEFINITION` or `--model-definition '<JSON>'`. See [the complete field/conflict contract](models.md#invocation-scoped-headless-models); credentials come only from the definition's `apiKeyEnv`. These selectors cannot be combined with `--provider`, `--model`, `--models` or `--api-key`.
+
+`get_state` and `get_available_models` expose the normal full model, including nonsecret endpoint/limits and a generated `invocation-<UUID>` provider, but not the captured credential. Use that returned provider and literal ID for later `set_model`. Model/thinking setters and cycling remain supported without saving default model/thinking preferences, even after switching models. `new_session` inherits the live selection; `switch_session` uses the supplied invocation model. All replacement registries retain the same definition/key and opt-out policy.
+
+Ordinary journal persistence remains enabled unless `--no-session` is supplied. Resupply the definition in a fresh process; reopening without it uses ordinary unavailable-model restoration warnings/fallback and never revives the endpoint/key. Invalid definitions/missing environment values fail startup with nonzero status before protocol service construction. A successful `prompt` response means acceptance, not successful generation: authentication, transport and stream failures arrive in subsequent assistant error/events, without silent route substitution. This feature does not change JSONL framing or RPC command/result shapes.
+
 ## Protocol Overview
 
 - **Commands**: JSON objects sent to stdin, one per line

package/docs/sdk.md

@@ -438,6 +438,19 @@ For each built-in provider request, `createAgentSession()` binds the current ext
 
 > See [examples/sdk/02-custom-model.ts](../examples/sdk/02-custom-model.ts)
 
+### Model preference persistence
+
+`createAgentSession()` and `createAgentSessionFromServices()` accept optional `persistModelPreferences` (default `true`); it is also available on `AgentSessionConfig`. Pass `false` to preserve saved default provider/model/thinking while allowing direct selection, both model-cycling paths and thinking changes to update live state, events and journal entries. Authentication and thinking clamping are unchanged. In an opt-out session, actual thinking-level changes on reasoning-capable models are remembered locally across non-reasoning detours, including an explicit `off` choice; the saved default remains unchanged. This local preference is not a new journal field or replacement-session inheritance value. With this opt-out, explicit startup selection also records changed branch-local model/thinking identity when opening an existing journal.
+
+```typescript
+const { session } = await createAgentSession({
+  model: myModel,
+  persistModelPreferences: false,
+});
+```
+
+This is not blanket settings suppression: unrelated settings writes remain possible. Runtime factories must forward the policy to every replacement session. The CLI's [invocation-definition selectors](models.md#invocation-scoped-headless-models) do this automatically, register the captured route through existing `ModelRegistry.registerProvider()`, and supply its credential through `AuthStorage.setRuntimeApiKey()`. Ingress helpers are not new package-root SDK exports; programmatic callers can continue using those existing registry/auth APIs. Journal identity alone cannot reconstruct an endpoint or credential in a fresh process.
+
 ### Context and output allocation
 
 Models and usage expose one authoritative total `contextWindow`; `contextWindowBudget` and `getContextWindowBudget()` are removed. See [the migration guide](models.md#breaking-migration-from-context-budgets) before updating external model definitions or consumers.
@@ -1053,6 +1066,10 @@ const mode = new InteractiveMode(runtime, {
 await mode.run();
 ```
 
+`/model` selection delegates preference persistence to the session, including `persistModelPreferences: false`.
+
+**Component migration:** the exported `ModelSelectorComponent` constructor no longer takes `settingsManager` as its third argument. Use `(tui, currentModel, modelRegistry, scopedModels, onSelect, onCancel, initialSearchInput?, outputThroughputHistory?)`; the selection callback must perform model selection through `session.setModel(model)` to retain authentication, journaling and preference policy. The component itself does not save defaults.
+
 ### runPrintMode
 
 Single-shot mode: send prompts, output result, exit:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leanandmean/coding-agent",
-  "version": "0.74.1-scramjet.70",
+  "version": "0.74.1-scramjet.71",
   "publishConfig": {
     "access": "public"
   },
@@ -37,9 +37,9 @@
     "test": "vitest --run --passWithNoTests"
   },
   "dependencies": {
-    "@leanandmean/agent": "0.74.1-scramjet.49",
-    "@leanandmean/ai": "0.74.1-scramjet.45",
-    "@leanandmean/tui": "0.74.1-scramjet.42",
+    "@leanandmean/agent": "0.74.1-scramjet.50",
+    "@leanandmean/ai": "0.74.1-scramjet.46",
+    "@leanandmean/tui": "0.74.1-scramjet.43",
     "@silvia-odwyer/photon-node": "^0.3.4",
     "chalk": "^5.5.0",
     "dictionary-en": "^4.0.0",