@niscorp/signal 0.1.3 → 0.1.4

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @niscorp/signal
 
+## 0.1.4
+
+### Patch Changes
+
+- a8b7133: DOCS.md states thirty-nine facts about the API that were written only in source comments, and describes `resolveTransport`.
+
+  `step()` and `stepStream()` now have their request and result fields described: the shape of a tool-calling transcript, `output.accept` and `output.outputTool`, what `toolCalls[].args` holds, what `usage.reported: false` means, `outcome`, `wire.rung` and `wire.recovered`, and the `reasoning` and `tool_call_delta` events. A new subsection gives `resolveTransport(spec, capabilities)`: every field of the spec and of the result. Also added: what `UNMEASURED_MODEL` assumes, `chatProviderEntry`, that `describe()` makes no request, that an OpenRouter row lists what the proxy accepts, and that `jev-latest` is an alias.
+
+  No behaviour changed.
+
+  **What to change:** nothing.
+
 ## 0.1.3
 
 ### Patch Changes

package/DOCS.md

@@ -37,7 +37,7 @@ Each provider has a capability profile that Signal uses to pick the right strate
 - **`nativeJsonMode`** — Can it guarantee JSON output?
 - **`toolsWithStructuredOutput`** — Is `response_format` accepted together with `tools` in one request?
 - **`validatesToolArgs`** — Does the endpoint validate tool-call arguments server-side and reject the request on a mismatch?
-- **`manglesNestedToolArgs`** — Does the model corrupt nested tool-call arguments?
+- **`manglesNestedToolArgs`** — Does the model corrupt nested tool-call arguments? For example, a nested array arrives as a JSON string.
 - **`multimodal`** — Does it accept image content?
 - **`supportsEmbedding`** — Can it convert text to vectors?
 
@@ -152,14 +152,25 @@ does) joined with the model's registry row (what the MODEL does, as
 measured by `scripts/probe-model.ts`). There is no override: a fact about
 a model is a row in `src/registry.ts`. A model with no row resolves to the
 conservative `UNMEASURED_MODEL`, and `describe().modelKnown` says so.
+`UNMEASURED_MODEL` assumes the least: `nativeJsonSchema: false`,
+`toolsWithStructuredOutput: false`, `manglesNestedToolArgs: true`,
+`multimodal: false`.
 A custom provider (by `baseUrl`) declares its own `capabilities`.
+`chatProviderEntry(id)` returns a chat provider's registry row, and
+`undefined` for an unknown id and for a decision provider.
 ```typescript
 createSignal('groq').describe()
 // { provider: 'groq', model: 'qwen/qwen3.8-27b', kind: 'chat', modelKnown: true, capabilities: {…} }
 ```
+`describe()` makes no request and does not need an API key. For a custom
+provider `modelKnown` is `false`, and `model` is `undefined` when none is set.
+
 A `reasoningEffort` the model's row does not list is refused when the
 client is built (`SignalError`, `E_VALIDATION_FAILED`), not by a provider 400
-mid-run. An unmeasured model is not checked.
+mid-run. An unmeasured model is not checked. On OpenRouter a row lists what
+the proxy accepts, which is not what the routed model honours: it passes
+`reasoning_effort` through to non-reasoning models too, so an accepted value
+does not mean the model reasons.
 
 ### `.onRetry(handler)`
 Hook called on each validation failure, including the last one that exhausts the retries.
@@ -221,6 +232,38 @@ Schema validation happens at the end of the stream; when the retries are spent t
 
 The low-level primitives `complete()` and `stream()` are built on: one model call, no tool execution, no schema retries. The caller owns the loop. `step()` takes a `StepRequest` (`messages`, `tools`, `toolChoice`, `output`, `responseFormat`, `options`) and returns a `StepResult` (`content`, `toolCalls`, `usage`, `finishReason`, `raw`, and — when the request carried `output.accept` — the routed `outcome` and `wire` report). `stepStream()` yields `text`, `reasoning` and `tool_call_delta` events and a final `done` carrying the `StepResult`.
 
+- **`messages`** — an assistant turn carries the calls it made as `toolCalls` (`{ id, name, args }`, `args` a JSON string) and has `content: ''` when it only called tools. Each result goes back as a `tool` message whose `toolCallId` is that call's `id`.
+- **`tools`** — each is `{ name, description, parameters }`; `parameters` is the JSON Schema of the tool's input (`z.toJSONSchema()` of a Zod schema).
+- **`output.accept`** — gates and does not transform: `outcome.value` is the accepted candidate itself, not the schema's parsed output, so a transform or a default in the schema is not applied.
+- **`output.outputTool`** — the name of an exit tool. A call to it is routed as output, never as a tool call.
+- **`responseFormat`** — passed to the provider as given. `step()` does not check it against the capabilities: with `tools` on a model without `toolsWithStructuredOutput`, the provider rejects the request.
+- **`toolCalls`** — a call's `args` is the parsed JSON value, or the provider's string when it does not parse. It is not checked against the tool's `parameters`.
+- **`usage`** — `reported: false` means the provider sent no usage and the numbers are an estimate (about 4 characters per token). A stream does not reliably carry its usage.
+- **`outcome`** — also present, without `output.accept`, on a result recovered from a provider rejection.
+- **`wire`** — `rung` names what produced the accepted output: `parse` for content that was valid JSON as it arrived, `call-args` for a call's arguments, otherwise the repair it took. `recovered` is set when the result was recovered from a provider rejection.
+- **`reasoning` events** — the model's thinking, never part of `content`. Only a provider that streams its reasoning produces them; on Groq and OpenRouter Signal asks for it only when `reasoningEffort` is set.
+- **`tool_call_delta` events** — each carries one fragment of a call's arguments (`argsText`) for the call at `index`. The assembled calls are in the `done` event's `toolCalls`.
+
+### `resolveTransport(spec, capabilities)`
+
+For a caller that runs its own loop over `step()`: resolves how an output contract travels — `respond` (the arguments of an exit tool), `native` (`response_format`) or `emit` (message content) — and returns what to put on each request. The `spec`:
+
+- **`wire`** — the full schema of the output contract. It is the `response_format` under `native` and the exit tool's params under `respond`. An endpoint with `validatesToolArgs` is never sent it as tool params.
+- **`looseWire`** — the same contract with the payload left untyped. It replaces `wire` as the exit tool's params when the contract has `data` and `wire` has no JSON Schema, has a `$ref` in it, or is longer than 8,192 characters as one.
+- **`hasData`** — whether the contract carries a typed payload (a `data` field).
+- **`forceTool`** — every turn must be a tool call: under `respond` the result carries `toolChoice: 'required'`. It makes `auto` resolve to `respond` where it would resolve to `emit`, and throws `E_VALIDATION_FAILED` with an explicit `emit`.
+
+The result:
+
+- **`respondDetail`** — under `respond`, how much of the contract the exit tool's params carry: `full` (`wire`), `loose` (`looseWire`) or `permissive` (the endpoint validates tool args, so the params name the envelope fields and constrain nothing).
+- **`respondDescriptor`** — under `respond`, the exit tool to append to the request's `tools`.
+- **`outputToolName`** — under `respond`, the exit tool's name (`RESPOND_TOOL_NAME`). Pass it as `output.outputTool`; the `tool_call_delta` events of a call with that name carry the output as it arrives.
+- **`responseFormat`** — under `native`, the `responseFormat` to send on every request.
+- **`toolChoice`** — `'required'` under `respond` with `forceTool`.
+- **`injectSchemaDoc`** — `true` when the contract has `data` and the transport does not carry its full schema (`emit`, and `respond` with `loose` or `permissive` params): the caller adds its own schema documentation to the prompt.
+- **`finishProtocol`** — the text that tells the model how the run ends under this transport. Add it unchanged as a system message, after any schema documentation.
+- **`corrections`** — the messages to send back when a turn did not finish (`termination`) or its output was invalid (`invalidOutput`). The caller replaces `{issues}` in `invalidOutput` with the evidence.
+
 ### `.count(input)`
 
 Rough token count for a string or a message list. A heuristic (about 4 characters per token), not a tokenizer.
@@ -286,7 +329,7 @@ const { response } = await createSignal('groq')
 
 1. Zod schema is converted to JSON Schema (draft-07)
 2. Based on capabilities:
-   - `nativeJsonSchema` (and, when tools are set, `toolsWithStructuredOutput`) → sends JSON Schema as `response_format`
+   - `nativeJsonSchema` (and, when tools are set, `toolsWithStructuredOutput`) → sends JSON Schema as `response_format`, with `strict: false`
    - otherwise `nativeJsonMode` and no tools → sends `response_format: json_object` + schema in a system message
    - otherwise → schema in a system message only
 3. The response is normalized by the wire layer (JSON extraction and repairs, each counted only if the result passes the schema)
@@ -466,7 +509,7 @@ result.decisions.urgency.level;      // 0 | 1 | 2 — index into criteria
 
 You declare the questions once and never write an output type. Signal derives both halves from them:
 
-- **The result type.** `choice` → the union of the `criteria` keys; `score` → a level index into `criteria`; `noul` → a boolean.
+- **The result type.** `choice` → the union of the `criteria` keys; `score` → a level index into `criteria`; `noul` → a boolean. A `score` question's `criteria` lists its levels lowest first.
 - **The acceptance gate.** The same derivation at runtime: a choice outside the asked options, a question left unanswered, a distribution over other keys, a probability outside [0, 1] — each fails the call with `E_VALIDATION_FAILED` and the provider's body under `context.raw`.
 
 There is no repair and no correction retry. A decision model writes no bytes to repair and cannot be told what it got wrong.
@@ -485,6 +528,8 @@ if (result.calibrated) {
 }
 ```
 
+On a decision provider `level` is the most probable level and `answer` is `noul >= 0.5`.
+
 On a chat provider `decide()` still works: the same questions run through structured output (native grammar where it exists, the repair ladder, correction retries) and come back as picks alone with `calibrated: false`. Signal does not invent a `1.0` — it would clear every threshold. Emulation is one to two orders of magnitude slower; a caller on a latency budget checks first:
 
 ```typescript
@@ -503,6 +548,8 @@ controller.abort(); // tears down the HTTP request
 
 A provider is one of two kinds. A **decision provider** (`typesafe`) has `decide()` and nothing else — `complete`, `stream`, `step`, `stepStream` and `embed` fail with `E_VERB_NOT_SUPPORTED` before any request is built. A **chat provider** has every verb, `decide()` included, by emulation.
 
+`typesafe`'s default model `jev-latest` is an alias for the provider's current version; `meta.model` is the version the provider reports having answered. A caller that records calibration against a version pins it with `.model('jev-1.13.0')`.
+
 A decision provider by base URL — self-hosted, or the fake a check runs — names its protocol:
 
 ```typescript

package/dist/index.cjs

@@ -52,17 +52,11 @@ var providerRegistry = {
     endpoint: {
       nativeTools: true,
       nativeJsonMode: true,
-      // Groq validates tool args server-side (tool_use_failed 400s).
       validatesToolArgs: true,
       supportsEmbedding: false
     },
     adapter: "openai-compatible",
-    // tool_use_failed / json_validate_failed 400s carry the model's
-    // attempt in failed_generation — recover and route it.
     wire: ["failed-generation"],
-    // Reasoning models stream their trace only when asked to parse it out;
-    // `reasoning_format` is rejected on the non-reasoning ones, which is why
-    // this is opt-in (see reasoningRequest above).
     reasoningRequest: { reasoning_format: "parsed" }
   },
   openai: {
@@ -77,8 +71,6 @@ var providerRegistry = {
       supportsEmbedding: true
     },
     adapter: "openai-compatible",
-    // 4o-era models occasionally emit JSONL where one value was asked
-    // for; the acceptance gate decides, so this can never misfire.
     wire: ["jsonl-lines"]
   },
   openrouter: {
@@ -93,8 +85,6 @@ var providerRegistry = {
       supportsEmbedding: false
     },
     adapter: "openai-compatible",
-    // OpenRouter unifies reasoning across the models it routes; `enabled` turns
-    // the trace on for those that have one and is ignored by those that don't.
     reasoningRequest: { reasoning: { enabled: true } }
   },
   anthropic: {
@@ -127,97 +117,78 @@ var providerRegistry = {
     id: "typesafe",
     baseUrl: "https://api.typesafe.ai/v1",
     envKey: "TYPESAFE_API_KEY",
-    // The moving alias. A caller that records calibration against a model pins
-    // a version (`jev-1.13.0`) with `.model()`.
     defaultModel: "jev-latest",
     adapter: "systemone"
   }
 };
 var modelRegistry = {
-  // ── groq ──
   "groq/qwen/qwen3.8-27b": {
     capabilities: { nativeJsonSchema: false, toolsWithStructuredOutput: false, manglesNestedToolArgs: true, multimodal: true },
-    // nested: 3 of 20 trials failed
     reasoningEfforts: ["none", "default", "low", "medium", "high"],
     verified: "2026-09-24"
   },
   "groq/openai/gpt-oss-120b": {
     capabilities: { nativeJsonSchema: true, toolsWithStructuredOutput: false, manglesNestedToolArgs: true, multimodal: false },
-    // nested: 1 of 20 trials failed
     reasoningEfforts: ["low", "medium", "high"],
     verified: "2026-09-24"
   },
   "groq/openai/gpt-oss-20b": {
     capabilities: { nativeJsonSchema: true, toolsWithStructuredOutput: false, manglesNestedToolArgs: true, multimodal: false },
-    // nested: 6 of 20 trials failed
     reasoningEfforts: ["low", "medium", "high"],
     verified: "2026-09-24"
   },
-  // ── openai ──
   "openai/gpt-4o": {
     capabilities: { nativeJsonSchema: true, toolsWithStructuredOutput: true, manglesNestedToolArgs: false, multimodal: true },
-    // nested: 0 of 20 trials failed
     reasoningEfforts: [],
     verified: "2026-09-24"
   },
   "openai/gpt-4o-mini": {
     capabilities: { nativeJsonSchema: true, toolsWithStructuredOutput: true, manglesNestedToolArgs: false, multimodal: true },
-    // nested: 0 of 20 trials failed
     reasoningEfforts: [],
     verified: "2026-09-24"
   },
   "openai/gpt-4.1-mini": {
     capabilities: { nativeJsonSchema: true, toolsWithStructuredOutput: true, manglesNestedToolArgs: false, multimodal: true },
-    // nested: 0 of 20 trials failed
     reasoningEfforts: [],
     verified: "2026-09-24"
   },
-  // ── openrouter ──
   "openrouter/qwen/qwen3.8-27b": {
     capabilities: { nativeJsonSchema: true, toolsWithStructuredOutput: true, manglesNestedToolArgs: false, multimodal: true },
-    // nested: 0 of 20 trials failed
     reasoningEfforts: ["none", "minimal", "low", "medium", "high", "xhigh", "max"],
     verified: "2026-09-24"
   },
   "openrouter/openai/gpt-4o": {
     capabilities: { nativeJsonSchema: true, toolsWithStructuredOutput: true, manglesNestedToolArgs: false, multimodal: true },
-    // nested: 0 of 20 trials failed
     reasoningEfforts: ["none", "minimal", "low", "medium", "high", "xhigh", "max"],
     verified: "2026-09-24"
   },
   "openrouter/openai/gpt-4o-mini": {
     capabilities: { nativeJsonSchema: true, toolsWithStructuredOutput: true, manglesNestedToolArgs: false, multimodal: true },
-    // nested: 0 of 20 trials failed
     reasoningEfforts: ["none", "minimal", "low", "medium", "high", "xhigh", "max"],
     verified: "2026-09-24"
   },
   "openrouter/openai/gpt-oss-120b": {
     capabilities: { nativeJsonSchema: false, toolsWithStructuredOutput: true, manglesNestedToolArgs: false, multimodal: false },
-    // nested: 0 of 20 trials failed
     reasoningEfforts: ["minimal", "low", "medium", "high", "xhigh", "max"],
     verified: "2026-09-24"
   },
   "openrouter/z-ai/glm-5.2": {
     capabilities: { nativeJsonSchema: true, toolsWithStructuredOutput: true, manglesNestedToolArgs: true, multimodal: false },
-    // nested: 1 of 20 trials failed
     reasoningEfforts: ["none", "minimal", "low", "medium", "high", "xhigh", "max"],
     verified: "2026-09-24"
   },
   "openrouter/openai/gpt-5.6-luna": {
     capabilities: { nativeJsonSchema: true, toolsWithStructuredOutput: true, manglesNestedToolArgs: false, multimodal: true },
-    // nested: 0 of 20 trials failed
     reasoningEfforts: ["none", "minimal", "low", "medium", "high", "xhigh", "max"],
     verified: "2026-09-24"
   },
   "openrouter/openai/gpt-oss-20b": {
     capabilities: { nativeJsonSchema: false, toolsWithStructuredOutput: true, manglesNestedToolArgs: false, multimodal: false },
-    // nested: 0 of 20 trials failed
     reasoningEfforts: ["minimal", "low", "medium", "high", "xhigh", "max"],
     verified: "2026-09-24"
   },
   "openrouter/meta-llama/llama-3.3-70b-instruct": {
     capabilities: { nativeJsonSchema: false, toolsWithStructuredOutput: true, manglesNestedToolArgs: true, multimodal: false },
-    // nested: 9 of 20 trials failed
     reasoningEfforts: ["none", "minimal", "low", "medium", "high", "xhigh", "max"],
     verified: "2026-09-24"
   }
@@ -381,9 +352,8 @@ var createOpenAICompatibleAdapter = async (config) => {
   async function* chatStream(request, options) {
     const streamParams = {
       ...buildParams(request),
-      // Ask for the reasoning trace only when the caller wants reasoning — the
-      // opt-in that keeps `reasoning_format` off a plain Groq call. Stream-only:
-      // the non-stream `chat` path never sees these, so its content is unmoved.
+      // Only when the caller set reasoningEffort: Groq answers `reasoning_format` with a 400
+      // on its non-reasoning models.
       ...request.options?.reasoningEffort !== void 0 && config.reasoningRequest !== void 0 ? config.reasoningRequest : {},
       stream: true,
       stream_options: { include_usage: true }
@@ -709,8 +679,6 @@ async function* executeStepStream(config) {
           contentBuffer += delta.text;
           yield { type: "text", text: delta.text };
           break;
-        // Reasoning is passed straight through and deliberately NOT added to
-        // contentBuffer: it is the model thinking, not its answer.
         case "reasoning":
           yield { type: "reasoning", text: delta.text };
           break;
@@ -1389,10 +1357,7 @@ var buildMessages = (config, input) => {
 var recoveredStepResult = (recovered, routed, raw, sent) => ({
   content: "",
   toolCalls: routed.outcome.kind === "tool_calls" ? routed.outcome.calls : [],
-  // A rejected generation costs tokens — the provider processed the request and
-  // billed for it — and the 400 body carries none. The prompt is known exactly
-  // and the model's attempt is in the rejection, so this is countable rather
-  // than lost. Marked unreported, because it is a reckoning.
+  // The provider bills a rejected generation and its 400 carries no usage.
   usage: estimateUsage(sent, recovered.rejection.argsText, routed.outcome.kind === "tool_calls" ? routed.outcome.calls : []),
   finishReason: "error_recovered",
   raw,
@@ -1447,10 +1412,6 @@ var createSignalFromConfig = (config) => {
       ...providerTools && { tools: providerTools },
       ...request.toolChoice !== void 0 && { toolChoice: request.toolChoice },
       ...request.responseFormat !== void 0 && { responseFormat: request.responseFormat },
-      // The client's own options are the floor; a request may override them
-      // field by field. `complete`/`stream` already run on config.options —
-      // step used to drop them, so a configured client behaved differently
-      // depending on which door the caller came through.
       ...(config.options !== void 0 || request.options !== void 0) && {
         options: { ...config.options, ...request.options }
       }
@@ -1485,8 +1446,7 @@ var createSignalFromConfig = (config) => {
     const result = {
       content: response.content,
       toolCalls,
-      // The non-streaming body always carries usage, so a zero here is a real
-      // zero rather than a missing frame.
+      // A non-streaming body always carries usage, so a zero here is a reported zero.
       usage: { ...response.usage, reported: true },
       finishReason: response.finishReason,
       raw: response.raw
@@ -1582,8 +1542,7 @@ var createSignalFromConfig = (config) => {
       decisions: acceptUncalibrated(request.questions, result.response, result.meta.provider.raw),
       meta: {
         model: result.meta.model,
-        // complete() sums what providers reported with what it had to estimate
-        // and does not say which, so this total cannot be vouched for as measured.
+        // complete() adds reported usage to estimated usage and does not say which.
         usage: { ...result.meta.usage, reported: false },
         durationMs: Date.now() - started,
         provider: { raw: result.meta.provider.raw }
@@ -1591,7 +1550,6 @@ var createSignalFromConfig = (config) => {
     };
   };
   return {
-    // Builder methods
     apiKey: (key) => fork({ apiKey: key }),
     model: (m) => fork({ model: m }),
     systemPrompt: (prompt) => fork({ systemPrompt: prompt }),
@@ -1621,7 +1579,6 @@ var createSignalFromConfig = (config) => {
         modelKnown: false
       };
     },
-    // Execution — thin wrappers over the step core (src/complete.ts).
     complete: async (input) => runComplete(
       {
         messages: buildMessages(config, input),
@@ -1647,10 +1604,8 @@ var createSignalFromConfig = (config) => {
       },
       { stepStream: stepStreamAs("stream"), model: resolveProvider(config).model, capabilities: resolveCapabilities(config) }
     ),
-    // ─── Low-level primitives — the execution core itself ────
     step,
     stepStream,
-    // ─── Embedding ────────────────────────────────────────────
     embed: (async (input, options) => {
       const adapter = await getChatAdapter("embed");
       if (!adapter.embed) {
@@ -1670,7 +1625,6 @@ var createSignalFromConfig = (config) => {
       }
       return response.embeddings;
     }),
-    // ─── Decisions ────────────────────────────────────────────
     decide: async (request) => {
       assertQuestions(request.questions);
       const started = Date.now();
@@ -1678,7 +1632,6 @@ var createSignalFromConfig = (config) => {
       const model = resolveProvider(config).model;
       return adapter.kind === "decisions" ? decideCalibrated(adapter, model, request, started) : decideEmulated(model, request, started);
     },
-    // ─── Low-level: token counting (heuristic) ───────────────
     count: async (input) => {
       const CHARS_PER_TOKEN2 = 4;
       if (typeof input === "string") {
@@ -1786,8 +1739,7 @@ var resolveTransport = (spec, caps) => {
       responseMode: spec.responseMode,
       responseFormat: {
         type: "json_schema",
-        // strict:false — strict mode rejects open records and several
-        // keywords; non-strict still constrains and never hard-fails.
+        // Strict mode rejects open records and several keywords; non-strict still constrains.
         jsonSchema: { name: "envelope", strict: false, schema: serialized }
       },
       injectSchemaDoc: injectSchemaDoc2,