@nemesis-oss/ollama-sdk 1.6.0 → 1.8.0

package/CHANGELOG.md

@@ -1,8 +1,20 @@
 # Changelog
 
-## Unreleased
+## [1.8.0] - 2026-10-02
 
-- **Runtime Zod validation (Wave 10).** `OllamaRuntime` now accepts a `validateRequests: true` option. When enabled, every request body is validated against the operation's generated Zod schema BEFORE any HTTP request is made. Malformed requests throw `OllamaRequestValidationError` (a new `OllamaClientError` subclass) with the Zod issues attached. Unknown fields are stripped (Zod's default behavior), so callers can't accidentally send extra fields the contract doesn't allow. Opt-in — zero overhead when disabled (the default). See [ADR 0020](./docs/adr/0020-runtime-zod-validation.md).
+- **Contract execution completion (Waves 12-16).** The SDK's contract-first architecture is now fully executable: every operation in the canonical IR is represented, generated, typed, and runtime-enforced with no `Record<string, unknown>` escape hatches on the generated surface.
+  - **Wave 12** — Contract execution hardening: transport-mode dispatch (SSE for compat, NDJSON for native), `maxRequestBytes` enforcement (413 client-side), auto-fetch `minOllamaVersion` via cached `/api/version`, typed OpenAI/Anthropic generated APIs, fully generated System One types, MCP input schemas from path params, generated schema-registry, Web Search/Web Fetch in the IR, structural path parameters, `checkBlob` 404-only semantics, single `verify:release` gate, deterministic IR.
+  - **Wave 13** — System One contract completion: exact upstream OpenAPI schemas (correct `confidence: number`, `noul: number`, `score: number`, `legend: Record`, `probabilities: Record`), string `pattern`/`minLength`/`maxLength` enforcement, conditional request size limits (64 KiB / 32 MiB with images), `OllamaClient.systemOne<Q>()` with key-safe generic answer access, opt-in `validateResponses` runtime path, live System One conformance against real Ollama with `tev1:0.8b`.
+  - **Wave 14** — Failover + decision helpers: `OllamaClient.runtime` participates in multi-endpoint failover via `FailoverHttpClient`, higher-level System One decision helpers (`choice()`, `noul()`, `score()`, `route()`, `verify()`, `rank()`).
+  - **Wave 15** — Contract execution completion: path parameter substitution (`{model}` → `gpt-4` with URI encoding), host-aware execution (web search/fetch route to `https://ollama.com` via `cloudHttp` backend), model-aware failover routing, MCP argument routing (path params split from body), `contract:validate` in CI and release, method+path operation-level discovery (catches missing HTTP methods on declared paths).
+  - **Wave 16** — Final hardening: security invariant tests (path traversal prevention, host injection prevention, abort propagation), System One exact generic answer correlation (`AnswerFor<Q>`), decision helper `verify()` semantic fix (`probability` not `confidence`), ADR 0022 documenting hybrid compatibility typing policy, version bump to 1.8.0.
+
+- **System One live-tour coverage.** The live feature tour now exercises `/v1/systemone` when the server is Ollama 0.35.0 or newer and a compatible local model is installed; otherwise it records a clear skip reason.
+
+## [1.7.0] - 2026-10-01
+
+- **Interactive MCP elicitation and task handling.** The stdio and HTTP connectors now support host-managed form/URL elicitation and configurable manual or automatic `input_required` handling. The bridge preserves task responses and exposes explicit task status, result, and cancellation methods without starting background polling.
+- **Consolidated live Ollama tour.** Added `npm run lab:live` to exercise the built public SDK against a local Ollama server, with real-time request/stream logs, JSONL results, and opt-in cloud/vision checks.
 
 ## [1.4.1] - 2026-10-01
 

package/README.md

@@ -73,6 +73,8 @@ The SDK exposes a transport-neutral `McpBridge` that converts MCP `tools/list` d
 - MCP JSON Schema is preserved in the generated Ollama tool definition.
 - `structuredContent` and non-text MCP content blocks are retained in the model-visible tool result.
 - MCP `isError: true` results remain model-readable; they are not treated as transport failures.
+- Manual `input_required` responses and legacy task creation/status results are preserved without silently polling.
+- Tools declaring `execution.taskSupport: "required"` are invoked as tasks only when the server advertises task calls; optional task use is opt-in.
 
 `loadMcpTools()` keeps the historical model-oriented string result by default. Set `resultMode: 'structured'` when application code needs the raw MCP `CallToolResult`, including `structuredContent`, content blocks, `isError`, and `_meta`:
 
@@ -113,6 +115,35 @@ await connection.close();
 console.log(result.finalMessage.content);
 ```
 
+The stdio and HTTP connectors accept host-provided elicitation handlers. The requested modes are declared as client capabilities before connection, and the host retains control over user interaction. Form handlers should display and validate the requested fields; URL handlers should show the destination and obtain consent before accepting or opening it. No URL is opened automatically:
+
+```typescript
+const connection = await connectStdioMcpClient(
+  { command: 'npx', args: ['-y', '@modelcontextprotocol/server-example'] },
+  {
+    elicitation: {
+      form: async (request) => collectAndValidateForm(request),
+      url: async (request) => {
+        const approved = await askUserToOpen(request.url, request.message);
+        return { action: approved ? 'accept' : 'decline' };
+      },
+    },
+    inputRequiredMode: 'manual',
+  },
+);
+```
+
+`inputRequiredMode` defaults to `manual` on these connectors. The bridge forwards `input_required` results unchanged (use `resultMode: 'structured'` for raw values), including their opaque `requestState` and keyed `inputRequests`; it does not solicit data or retry the tool call itself. Set `inputRequiredMode: 'automatic'` to let the MCP client use the registered elicitation handlers and retry internally. In manual mode, the host can gather responses and retry with the same `requestState`:
+
+```typescript
+await connection.client.callTool(
+  { name, arguments: args, inputResponses, requestState },
+  { allowInputRequired: true },
+);
+```
+
+For legacy task-capable servers, required task tools are invoked using task augmentation. Optional task-capable tools remain synchronous unless `taskMode: 'all-supported'` is set. Set `taskTtlMs` to request a task lifetime. Task creation and `input_required` task statuses are preserved (serialized as JSON in text mode); no polling starts automatically. The host controls progress with `bridge.getTaskStatus(taskId)`, retrieves a completed payload with `bridge.getTaskResult(taskId)`, and can stop work with `bridge.cancelTask(taskId)`.
+
 Use `connection.terminateSession()` when the remote Streamable HTTP server exposes a session you want to terminate explicitly. Legacy SSE connections do not expose that method.
 
 The MCP TypeScript SDK v2 treats Streamable HTTP as the preferred remote transport and keeps SSE as a legacy fallback during migration. citeturn514654search0turn514654search6