@orkestrel/scaffold 0.0.140 → 0.0.142
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/bin/main.js +1 -1
- package/dist/host/agents/skills/orkestrel-harden/references/bindings.md +2 -1
- package/dist/host/claude/agents/orkestrel.md +4 -4
- package/dist/host/claude/rules/architecture.md +4 -2
- package/dist/host/claude/rules/typescript.md +23 -10
- package/dist/host/claude/rules/workspace.md +9 -9
- package/dist/host/configs/policy.ts +174 -11
- package/dist/host/dotfiles/oxlintrc.json +595 -0
- package/dist/host/guides/agent.md +447 -531
- package/dist/host/guides/ollama.md +44 -12
- package/dist/host/guides/study.md +2680 -760
- package/dist/host/manifest.json +12 -12
- package/dist/host/tests/config.test.ts +226 -7
- package/dist/src/core/index.cjs +4 -4
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.js +4 -4
- package/dist/src/core/index.js.map +1 -1
- package/package.json +1 -1
|
@@ -103,7 +103,7 @@ Beside those rows, the core face exports what the constructors and the leaves co
|
|
|
103
103
|
| `ollamaJudgeOptionsShape` | const | `import("@orkestrel/contract").ObjectShape<{ model: import("@orkestrel/contract").StringShape; system: import("@orkestrel/contract").StringShape; calibration: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").ObjectShape<{ temperature: import("@orkestrel/contract").NumberShape; }, boolean \| import("@orkestrel/contract").ContractShape>>; url: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; keepAlive: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").UnionShape<readonly [import("@orkestrel/contract").StringShape, import("@orkestrel/contract").NumberShape]>>; options: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").ObjectShape<{}, true>>; truncate: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").BooleanShape>; timeout: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; }, false>` | Describes the serializable part of `OllamaJudgeOptions`, the record a judge's constructor checks exactly. |
|
|
104
104
|
| `ollamaOptionsContract` | const | `ContractInterface<unknown>` | Holds the compiled contract a provider's constructor checks its serializable options against. |
|
|
105
105
|
| `ollamaJudgeOptionsContract` | const | `ContractInterface<unknown>` | Holds the compiled contract a judge's constructor checks its serializable options against. |
|
|
106
|
-
| `OLLAMA_CONTEXT_REMEDY` | const | `"the prompt exceeds the model's context window;
|
|
106
|
+
| `OLLAMA_CONTEXT_REMEDY` | const | `"the prompt exceeds the model's context window; serve the conversation through createLedger to bound every request, raise options.num_ctx, or set truncate: true to let the daemon cut it"` | Names what a chat refusal appends when the daemon's text names the context window. |
|
|
107
107
|
| `OLLAMA_JUDGE_CONTEXT_REMEDY` | const | `"the prompt exceeds the model's context window; shorten the state, raise options.num_ctx, or set truncate: true to let the daemon cut it"` | Names what a judge refusal appends when the daemon's text names the context window. |
|
|
108
108
|
| `scanOptionFaults` | function | `(contract: ContractInterface<unknown>, options: object, live: readonly string[]) => readonly AuditFault[]` | Scans a constructor's options against a contract, leaving out the live values and every key set to `undefined`. |
|
|
109
109
|
| `matchesContextRefusal` | function | `(text: string) => boolean` | Checks whether a daemon's refusal text names the context window. |
|
|
@@ -122,7 +122,7 @@ The reach is measured on one model and one daemon. On Ollama 0.40.14 with `qwen3
|
|
|
122
122
|
|
|
123
123
|
A false positive costs an invisible character: text that spells a listed token reaches the model with U+200B inside it, and a model can copy that character into a file.
|
|
124
124
|
|
|
125
|
-
`OllamaProvider` declares `name` (`'ollama'`) and inherits the rest of its data members from the base: `id` is the stable per-instance trace label, and `replay` selects which stored assistant reasoning reaches the provider input (default `'none'`). The Ollama request mapper omits stored reasoning from the wire regardless of that policy. Its wire seams are documented under [Methods](#methods), and the `generate` / `stream` boundary it inherits under `AgentProviderInterface` in [`agent.md`](agent.md). `AgentProvider` / `AgentProviderInterface` / `ProviderInterface` / `ProviderOptions` / `ProviderRequest` / `ProviderIncrement` / `ProviderParserInterface` / `ProviderResult` / `ProviderDelta` / `ProviderStreamOptions` / `ProviderError` / `isProviderError` / `ProviderAbortError` / `isProviderAbortError` / `Message` / `ContextSectionFormat` / `InstructionInterface` are owned by `@orkestrel/agent`; `ToolDefinition` / `ToolCall` by `@orkestrel/tool`; the `TokenUsage` shape by `@orkestrel/budget`; `createNDJSONParser` by `@orkestrel/ndjson`. All are reused here, never redefined. The agent package also owns the `JudgeInterface` interface, `JudgeRequest` type, `JudgeResult` interface, `JudgeAnswer` type, `Refusal` interface, `AgentJudge` class, `JudgeError` class, `JudgeAbortError` class, and `measureAnswer` function.
|
|
125
|
+
`OllamaProvider` declares `name` (`'ollama'`) and inherits the rest of its data members from the base: `id` is the stable per-instance trace label, `model` is the tag the constructor received, which every request body names, and `replay` selects which stored assistant reasoning reaches the provider input (default `'none'`). The Ollama request mapper omits stored reasoning from the wire regardless of that policy. Its wire seams are documented under [Methods](#methods), and the `generate` / `stream` boundary it inherits under `AgentProviderInterface` in [`agent.md`](agent.md). `AgentProvider` / `AgentProviderInterface` / `ProviderInterface` / `ProviderOptions` / `ProviderRequest` / `ProviderIncrement` / `ProviderParserInterface` / `ProviderResult` / `ProviderDelta` / `ProviderStreamOptions` / `ProviderError` / `isProviderError` / `ProviderAbortError` / `isProviderAbortError` / `Message` / `ContextSectionFormat` / `InstructionInterface` are owned by `@orkestrel/agent`; `ToolDefinition` / `ToolCall` by `@orkestrel/tool`; the `TokenUsage` shape by `@orkestrel/budget`; `createNDJSONParser` by `@orkestrel/ndjson`. All are reused here, never redefined. The agent package also owns the `JudgeInterface` interface, `JudgeRequest` type, `JudgeResult` interface, `JudgeAnswer` type, `Refusal` interface, `AgentJudge` class, `JudgeError` class, `JudgeAbortError` class, and `measureAnswer` function.
|
|
126
126
|
|
|
127
127
|
The raw judge exports the following declarations.
|
|
128
128
|
|
|
@@ -204,6 +204,28 @@ The session composes the following validators and protocol helpers, each exporte
|
|
|
204
204
|
|
|
205
205
|
`OllamaDaemonInterface` keeps its data members in its row: `url` is the declared origin, `identity` is the verified startup receipt (`undefined` before verification and kept after stop), `maintenance` is every unload attempt in sequence order, and `emitter` is the typed lifecycle surface. Its lifecycle methods are documented under [Methods](#methods). `DuplexOptions` is owned by `@orkestrel/process`, and `EmitterInterface`, `EmitterHooks`, and `EmitterErrorHandler` by `@orkestrel/emitter`; the server face reuses them and redefines none of them.
|
|
206
206
|
|
|
207
|
+
The server face also exports a loopback protocol fixture, which hands each logged request to a reply callback before any built-in answer, together with its options guard and the builders that write Ollama's wire bodies.
|
|
208
|
+
|
|
209
|
+
| Name | Kind | Signature | Summary |
|
|
210
|
+
| ------------------------ | --------- | ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
|
|
211
|
+
| `createOllamaFixture` | function | `(options: OllamaFixtureOptions) => Promise<OllamaFixtureInterface>` | Creates a fixture and resolves after it listens. |
|
|
212
|
+
| `OllamaFixture` | class | `new (options: OllamaFixtureOptions) => OllamaFixtureInterface` | Serves Ollama's protocol on a loopback port, handing each logged request to the reply callback before any built-in answer. |
|
|
213
|
+
| `OllamaFixtureInterface` | interface | `{ url, requests, emitter, start(), destroy() }` | Owns a loopback Ollama protocol fixture from `start` through `destroy`. |
|
|
214
|
+
| `OllamaFixtureOptions` | interface | `{ on?, error?, models, version, context, reply? }` | Configures a fixture's listed models, reported version, context length, reply callback, and listeners. |
|
|
215
|
+
| `OllamaFixtureRequest` | interface | `{ method, path, headers, body }` | Records one received request: its method, path, headers, and whole body text. |
|
|
216
|
+
| `OllamaFixtureHandler` | type | `(request: OllamaFixtureRequest, signal: AbortSignal) => Response \| undefined \| Promise<Response \| undefined>` | Defines the reply callback, which answers a logged request with a `Response` or declines it with `undefined`. |
|
|
217
|
+
| `OllamaFixtureEventMap` | type | `{ readonly request: readonly [request: OllamaFixtureRequest]; readonly error: readonly [error: unknown]; }` | Reports logged requests and serving failures. |
|
|
218
|
+
| `isOllamaFixtureOptions` | function | `(value: unknown) => value is OllamaFixtureOptions` | Checks whether a value configures a fixture with unique model names, a nonempty version, and a positive integer context. |
|
|
219
|
+
| `buildOllamaAnswer` | function | `(request: OllamaFixtureRequest, options: Pick<OllamaFixtureOptions, 'models' \| 'version' \| 'context'>) => Response` | Builds the answer a fixture gives a request its reply callback declines. |
|
|
220
|
+
| `buildOllamaReply` | function | `(options?: OllamaReplyOptions) => string` | Builds an NDJSON chat reply: a delta row for each part, then one terminal row. |
|
|
221
|
+
| `buildOllamaReadout` | function | `(options: OllamaReadoutOptions) => string` | Builds a one-token raw generate reply carrying the token's top logprob list. |
|
|
222
|
+
| `buildOllamaInventory` | function | `(models: readonly OllamaModel[]) => string` | Builds a `/api/tags` listing body for the given models, in the shape a real daemon sends. |
|
|
223
|
+
| `buildOllamaTiming` | function | `(durations?: Partial<OllamaDurations>, counts?: Partial<OllamaCounts>) => Readonly<Record<string, number>>` | Builds the timing fields of a terminal wire record, leaving out every member that is not set. |
|
|
224
|
+
| `OllamaReplyOptions` | interface | `{ model?, content?, parts?, thinking?, calls?, reason?, counts?, durations? }` | Configures a chat reply's delta rows and its terminal row. |
|
|
225
|
+
| `OllamaReadoutOptions` | interface | `{ model?, token, top, counts? }` | Configures a one-token judge readout: the chosen token, its top list, and an optional model and counts. |
|
|
226
|
+
| `OLLAMA_FIXTURE_KEYS` | const | `readonly string[]` | Lists the keys the fixture options admit, live values included. |
|
|
227
|
+
| `OLLAMA_FIXTURE_TIME` | const | `"2026-10-23T14:08:45.7014834Z"` | Names the fixed timestamp a fixture writes as each listed model's `modified_at` and each unload reply's `created_at`. |
|
|
228
|
+
|
|
207
229
|
## Methods
|
|
208
230
|
|
|
209
231
|
Each following table lists the methods one class or interface declares. The wire seams `OllamaProvider` declares are exactly the members of `AgentProviderInterface` that the base leaves open. The runtime never calls them directly: a caller drives `generate` or `stream`, and the engine calls these to frame, project, decode, and drain the Ollama wire. Those inherited calls, the `id` / `name` / `format` data members, and the `ProviderParserInterface` the seam returns are documented in [`agent.md`](agent.md).
|
|
@@ -239,9 +261,18 @@ A caller drives these methods directly, in the order [Daemon session](#daemon-se
|
|
|
239
261
|
| `stop` | `Promise<boolean>` | Permanently stops the owned tree, joins its session, and re-hashes the executable. |
|
|
240
262
|
| `destroy` | `Promise<void>` | Stops the daemon and releases its observation emitter after cleanup settles. |
|
|
241
263
|
|
|
264
|
+
#### `OllamaFixtureInterface`
|
|
265
|
+
|
|
266
|
+
`createOllamaFixture` calls `start` before it resolves, and a caller calls `destroy` when it is done. `OllamaFixture` implements both and exposes no other public method.
|
|
267
|
+
|
|
268
|
+
| Method | Returns | Summary |
|
|
269
|
+
| --------- | --------------- | --------------------------------------------------------------------------------------------------------- |
|
|
270
|
+
| `start` | `Promise<void>` | Listens on an ephemeral port on `127.0.0.1` and records the origin in `url`. |
|
|
271
|
+
| `destroy` | `Promise<void>` | Aborts every callback signal, cancels each held body, closes the listener, and releases the emitter last. |
|
|
272
|
+
|
|
242
273
|
## Contract
|
|
243
274
|
|
|
244
|
-
These invariants hold across `src/core`, `src/server`, and `ollama.md`. The doc ↔ source bijection and the method bijection cover both faces, and the rest state the core face; [Daemon session](#daemon-session) states the
|
|
275
|
+
These invariants hold across `src/core`, `src/server`, and `ollama.md`. The doc ↔ source bijection and the method bijection cover both faces, and the rest state the core face; [Daemon session](#daemon-session) states the daemon session's lifecycle, detection forms, and limits. The engine contract itself — `ProviderInterface`, `AgentProvider`, `ProviderResult`, `ProviderError`, `ProviderAbortError` — is in `@orkestrel/agent`, and [`agent.md`](agent.md) states it.
|
|
245
276
|
|
|
246
277
|
1. **Doc ↔ source bijection.** Every `function` / `class` / `const` / `interface` / `type` row in the `## Surface` tables is a real export of the `src/core` or `src/server` surface, and every export of either barrel appears as a Surface row — exhaustive, both directions.
|
|
247
278
|
2. **Imports each boundary from its owner, no cycle.** `OllamaProvider` extends `AgentProvider` and implements `AgentProviderInterface`; that base, `ProviderRequest`, `ProviderIncrement`, `ProviderParserInterface`, `ProviderInterface`, `ProviderOptions`, and `Message` come from `@orkestrel/agent`. `createNDJSONParser` comes from `@orkestrel/ndjson`, `ToolCall` from `@orkestrel/tool`, `TokenUsage` from `@orkestrel/budget`, and the guards (`isRecord` / `isString` / `isNumber` / `isNonNegativeInteger` / `parseJSONAs`) from `@orkestrel/contract`. The provider errors are owned by `@orkestrel/agent` and `ToolDefinition` by `@orkestrel/tool`: `src/core` throws those errors for a malformed record or malformed options, and the base accepts the `ToolDefinition[]` a call advertises. `describeFaults` comes from `@orkestrel/tool` and writes a refused option's lines. Each dependency is one-way and never imports from `@src/core`. No module under `src/` imports `@orkestrel/timeout` — the base arms the deadline — and the manifest declares it as a development dependency for the guide's bounding pattern, which imports it as a consumer would.
|
|
@@ -254,13 +285,13 @@ These invariants hold across `src/core`, `src/server`, and `ollama.md`. The doc
|
|
|
254
285
|
9. **Boundary narrowing — all wire `unknown` through guards, never `as`.** Every value read off the wire (each NDJSON record, `message`, `content`, `thinking`, the usage counts, `tool_calls`, `arguments`) arrives as `unknown` and is narrowed through the `@orkestrel/contract` guards — never a type assertion. A record that leaves out `message`, `content`, `thinking`, or `tool_calls` reads as empty, and one that carries any of them malformed refuses as `ProviderError` `'PROTOCOL'` — the one external boundary kept honest.
|
|
255
286
|
10. **The base owns everything that is not the wire.** The per-call deadline (`OllamaOptions.timeout`, `120_000`ms when omitted, folded with the caller's signal so either cancels the request and the timer is always cleared), the cancellation rule (a `stream` cancelled mid-flight throws `ProviderAbortError` carrying the partial, and the reader and parser are released in a `finally`), the transport seam (`OllamaOptions.fetch` and the per-request `OllamaOptions.headers` hook, awaited inside the deadline and raced against the combined signal), and the bounded error read all live in `AgentProvider`. `OllamaOptions` extends `ProviderOptions`, so those keys are the base's and behave identically for every provider built on it; [`agent.md`](agent.md) defines those rules.
|
|
256
287
|
11. **Context framing.** An instruction manager accepts a `ContextSectionFormat<InstructionInterface>` through `createInstructionManager({ format })`. The agent uses that manager to build the instruction text. Ollama structured output uses the separate per-call `ProviderStreamOptions.schema` value, forwarded as the wire `format` field.
|
|
257
|
-
12. **Event-free.** The provider and the judge are a pure functional boundary — no Emitter, no events. Each call is a function of its arguments. The server face's daemon session
|
|
288
|
+
12. **Event-free.** The provider and the judge are a pure functional boundary — no Emitter, no events. Each call is a function of its arguments. The server face's daemon session and protocol fixture are the package's emitters, through `OllamaDaemonInterface.emitter` and `OllamaFixtureInterface.emitter`.
|
|
258
289
|
13. **A core face that runs in a browser.** The `.` entry is built from `src/core`, which imports no `node:*` module and no DOM global; the scoped core typecheck compiles it with the `ESNext` and `WebWorker` libraries and no ambient `@types`, so neither Node's globals nor the DOM's are in scope, and the base binds `globalThis.fetch` to its own receiver so a browser does not throw `Illegal invocation` on a bare transport reference. The `./server` entry, built from `src/server`, imports Node modules and the process session, so a browser bundle takes the `.` entry alone. [`tests/service/page.test.ts`](../tests/service/page.test.ts) gates that claim rather than recording it: it launches the host's own Chrome or Edge through `@orkestrel/browser`, serves the built `@orkestrel/ollama` core entry and its whole `@orkestrel` import closure from an import map on a `127.0.0.1` fixture, and reads the page's requests from the browser's own request log. The page loads with no uncaught error and no console error, on the recorders a deliberate page fault then makes report; an `Agent` holding a page-defined DOM-writing `Tool` completes a tool loop against the live daemon through a same-origin `createRelay` server, where the model's recorded call reaches the page, the tool's minted receipt is read back out of the real DOM and found again as the `role: 'tool'` message of the relay request and the `/api/chat` request that follow the turn the call was dispatched in, and the run settles with `partial: false`; the page issues exactly one `POST /inference` per turn and nothing else across the whole operation window, with a deliberate `/control` request proving such a window can report one; a wrong bearer arrives as `ProviderError` with code `'HTTP'` and status `401` with no daemon request made; and `createOllama` in the page answers a prompt over `/api/chat` on the daemon's own origin after `requireDaemonOrigin` confirms the daemon permits the page's origin. Each attempt ends within its allowance plus its release share, so nothing the attempt schedules outlasts the case that holds it. The attempt's signal cancels the part of the connection the installed `BrowserOptions.signal` races — discovery, the port-free check, the launch, and `client.connect()` — and the attempt's own race is what bounds every phase after that, the target listing the connection ends with included; [`tests/service/page.test.ts`](../tests/service/page.test.ts) and the `PAGE_BOUNDS` table it spends state the mechanism. The model's choice to call a tool is retried at most 3 times, and that choice is the only reading another attempt buys: every attempt retains its observations before any page read can throw, and only a run that completed an answer without dispatching the tool spends another launch. An acquisition, read, release, or run failure ends the retry, and so does a run that deadline interrupted before it settled — an interrupted run reports no tool call for a reason another launch cannot clear, so retrying it would report the exhaustion as the model never choosing the tool. The request accounting is asserted over each retained attempt, so what the gate establishes is that the model called the tool within those attempts and that no attempt's traffic went unread. The daemon is the remaining limit — a page reaches `/api/chat` directly only where the daemon, or a proxy in front of it, answers the page's origin; otherwise relay the call through your own server ([Relaying through your own server](#relaying-through-your-own-server)).
|
|
259
290
|
14. **Tested live against a real local Ollama (no `skipIf`).** The live tests run against a real Ollama daemon — no mocks, only genuine third-party calls — model `qwen3.5:4b-q4_K_M`, with `OLLAMA_HOST` / `OLLAMA_MODEL` overridable. Unlike the other surfaces, the dedicated `service` project requires the daemon: `tests/setupService.ts` throws a clear error if it is unreachable and warms the model (a `num_predict: 1` chat) before the suite, so the live tests run unconditionally (no `describe.skipIf`). The project runs serially (`fileParallelism: false`) with a 120s test/hook timeout so a cold load cannot flake it; `keep_alive` keeps the model resident across files, and `bash scripts/ollama.sh` brings the daemon and model up before the battery in CI. Assertions are structural — they hold whatever wording a small model produces — and never pin exact output. The hermetic half sits in `tests/src/core/`, and the relay round trip is proved hermetically in [`tests/src/core/integration.test.ts`](../tests/src/core/integration.test.ts) and live in [`tests/service/relay.test.ts`](../tests/service/relay.test.ts).
|
|
260
|
-
15. **Doc ↔ source method bijection.** Each `## Methods` table lists the methods its class or interface declares: `frame`, `encode`, `read`, and `finish` for `OllamaProvider`; `encode` and `read` for `OllamaJudge`; `start`, `unload`, `stop`, and `destroy` for `OllamaDaemonInterface`, which `OllamaDaemon` implements with no other public method. The inherited `generate`, `stream`, and `ask` methods are declared by the agent package's engines, and the two overrides of `stream` and `ask` add only the context remedy.
|
|
291
|
+
15. **Doc ↔ source method bijection.** Each `## Methods` table lists the methods its class or interface declares: `frame`, `encode`, `read`, and `finish` for `OllamaProvider`; `encode` and `read` for `OllamaJudge`; `start`, `unload`, `stop`, and `destroy` for `OllamaDaemonInterface`, which `OllamaDaemon` implements with no other public method; and `start` and `destroy` for `OllamaFixtureInterface`, which `OllamaFixture` implements with no other public method. The inherited `generate`, `stream`, and `ask` methods are declared by the agent package's engines, and the two overrides of `stream` and `ask` add only the context remedy.
|
|
261
292
|
|
|
262
293
|
16. **Render.** The raw prompt mirrors the TypeSafe adapter path of Mica's server: the `rows_from_request` function in the `typesafe_server.py` file followed by the `prompt_for` function in the `native.py` file. Structured state uses JSON with a one-space indent and JavaScript numeric spelling: JavaScript cannot distinguish 100.0 from 100 and spells an exponent as 1e-7 where Python spells 1e-07. Parity is byte-exact for string states and structured states whose numbers spell the same in both runtimes. The wire preserves the system prompt and escapes control tokens in state, instructions, option names, and descriptions with U+200B after the opening angle bracket. Noul criteria render false before true; an absent or empty side renders its key. A question with blank instructions and no candidate text refuses with the `QUESTION` code, because a choice's name counts as text and nothing else would reach the model. Choice names render in brackets unless empty, positional (including Unicode decimal digits), or equal to the wire label. A null description renders the `None` text. Score levels omit names. The assistant suffix disables thinking with the `<think>\n\n</think>\n\n` text.
|
|
263
|
-
17. **Readout.** The wire sends each question in its own `POST` request to the `OLLAMA_GENERATE_PATH` endpoint. Each body carries the `raw: true`, `stream: false`, `logprobs: true`, `top_logprobs: 20`, and `truncate: false` settings; `OllamaJudgeOptions.truncate` sets the last. The fixed `num_predict: 1` and `temperature: 1` settings override the caller's sampling settings. Calibration divides candidate logprob gaps by its finite positive temperature before a softmax over candidates alone. The `extractTopLogprobs` function reads only the `logprobs[0].top_logprobs` list and preserves token text. Malformed
|
|
294
|
+
17. **Readout.** The wire sends each question in its own `POST` request to the `OLLAMA_GENERATE_PATH` endpoint. Each body carries the `raw: true`, `stream: false`, `logprobs: true`, `top_logprobs: 20`, and `truncate: false` settings; `OllamaJudgeOptions.truncate` sets the last. The fixed `num_predict: 1` and `temperature: 1` settings override the caller's sampling settings. Calibration divides candidate logprob gaps by its finite positive temperature before a softmax over candidates alone. The `extractTopLogprobs` function reads only the `logprobs[0].top_logprobs` list and preserves token text. Malformed entries raise a `JudgeError` error with the `PROTOCOL` code, even when a token repeats. A top list that repeats a token refuses that question, and its `missing` collection names every candidate key. The wire reads usage from a completed record through the `extractUsage` function, and a present count that is not a finite nonnegative number raises the `PROTOCOL` code. A `model` that is present and is not the configured tag raises the same code.
|
|
264
295
|
18. **Refusal.** A label outside the top list refuses that question. The `missing` collection names the caller's option, level index, or the `false` or `true` key. The wire still answers the other questions and the result keeps the spent usage. A missing label never receives an invented probability.
|
|
265
296
|
19. **Limits.** A choice admits 2 to 20 options and a score 2 to 10 levels. A request outside those limits raises a `JudgeError` error with the `QUESTION` code. Structured instructions or criteria raise the same error before inference because the Mica server flattens them with Python's `str()` function. The engine validates every body before making a transport call. The `keepAlive` setting accepts a duration string or a number and defaults to the `DEFAULT_KEEP_ALIVE` value. The daemon enforces its context window, and an over-long prompt raises a `JudgeError` error with the `HTTP` code, status 400, and `OLLAMA_JUDGE_CONTEXT_REMEDY`. The caller selects the wire.
|
|
266
297
|
20. **Identity and cancellation.** The `judge.model` property and every `JudgeResult.model` property carry a JSON tuple of the model tag, system prompt, effective calibration temperature, effective options with sorted keys, and the `MICA_RENDER_REVISION` value. The effective options include the fixed `num_predict: 1` and `temperature: 1` settings. A judge set to `truncate: true` appends the switch to the tuple, because a cut prompt can answer differently, and the default leaves the tuple unchanged, because a prompt that fits renders and answers the same. Equal option bags yield one identity regardless of key order; a changed effective option changes it. Each call has the inherited deadline and header hook. Cancellation raises a `JudgeAbortError` error carrying the completed calls' answers, refusals, and usage.
|
|
@@ -579,6 +610,7 @@ const messages = [{ id: '1', role: 'user', content: 'Say hello.' }] as const
|
|
|
579
610
|
|
|
580
611
|
const browser = createRelayProvider({
|
|
581
612
|
url,
|
|
613
|
+
model: 'qwen3.5:2b-q4_K_M', // the model the server half's provider serves
|
|
582
614
|
headers: () => ({ authorization: 'Bearer session-token' }),
|
|
583
615
|
})
|
|
584
616
|
const relayed = await browser.generate(messages, abort.signal)
|
|
@@ -676,7 +708,7 @@ A provider and a judge send `truncate: false`, so the daemon refuses a prompt ov
|
|
|
676
708
|
- **`truncate` omitted or `true`.** The daemon answers HTTP 200 with `done_reason: 'stop'`, the earlier turn dropped whole, and nothing that flags the cut: asked what the first note says, the model invented an answer. `read` has nothing to project, so `ProviderResult.truncated` stays absent.
|
|
677
709
|
- **`shift`.** `shift: false` stops no prompt cut. At 2014 prompt tokens of 2048 with `num_predict: 300`, `shift` omitted, `true`, and `false` each ended with HTTP 200, `done_reason: 'length'`, and an `eval_count` of 34, so the daemon stops at the window and `read` reports that as `truncated`. `OllamaOptions.shift` stays an option a host sets, and the provider sends no key otherwise.
|
|
678
710
|
|
|
679
|
-
|
|
711
|
+
Serve the conversation through `createLedger`, which bounds every request it sends, raise `options.num_ctx`, or set `truncate: true` to let the daemon cut the prompt.
|
|
680
712
|
|
|
681
713
|
The default changes the request body, so `StudyOllamaReplay` refuses a recorded prefix made before it. That is a new replay lineage, so screen the model and the daemon again before you record it, as you would after a daemon change.
|
|
682
714
|
|
|
@@ -829,7 +861,7 @@ timing?.invalid // []
|
|
|
829
861
|
- **Give a thinking model headroom** — with `think: true`, a reasoning model (for example `qwen3.5:2b` at `temperature: 0`) can spend 200+ tokens on `message.thinking` before any `content` token arrives; a tight `num_predict` cap ends the turn before content starts, yielding empty `result.content` with `result.truncated` set, and a tight external token budget exhausts on the usage the turn reports. Size `num_predict` and the budget with thinking overhead in mind for any model run with `think: true`.
|
|
830
862
|
- **Read the model layer** — a `num_predict` cap reached sets `result.truncated`, and an agent run ending there reports `stop.layer: 'model'`. A prompt the daemon cuts under `truncate: true` returns normally and is not reported.
|
|
831
863
|
- **Tune through `options`** — pass sampling parameters (`temperature`, `seed`, and `num_predict`) through `OllamaOptions.options`; they forward verbatim to the wire.
|
|
832
|
-
- **Keep the refusal** — leave `OllamaOptions.truncate` at its `false` default so an oversized prompt refuses, and
|
|
864
|
+
- **Keep the refusal** — leave `OllamaOptions.truncate` at its `false` default so an oversized prompt refuses, and serve the conversation through `createLedger` or raise `options.num_ctx` to fit it. Set `truncate: true` only where losing the earlier turns silently is acceptable.
|
|
833
865
|
- **Observe at the call site** — the provider publishes no events; read `stream`'s deltas and its returned result for everything a turn produced.
|
|
834
866
|
|
|
835
867
|
## Tests
|
|
@@ -849,12 +881,12 @@ The daemon session proofs run in the `src:server` project against `tests/src/ser
|
|
|
849
881
|
|
|
850
882
|
The hermetic projects — `src:core`, `src:server`, `setup`, `guides`, `conformance`, `policy`, and `config` — run with no Ollama daemon and no network beyond loopback. The `src:server` project starts no Ollama executable: its lifecycle proofs spawn the fake daemon and bind loopback ports only. The `service` project requires a warm local Ollama and, for the page proof, a Chromium-family browser and a built `dist`, and for the daemon session proof an executable on `PATH`, an `OLLAMA_DAEMON_EXECUTABLE` path, or an explicit `OLLAMA_DAEMON_DECLARATION` value; `distribution` packs and installs the artifact. The import guard reads `distribution` with the hermetic projects, because it never reaches the daemon; it leaves out `probe` and `service` alone, the two projects that may.
|
|
851
883
|
|
|
852
|
-
- [`tests/guides.test.ts`](../tests/guides.test.ts) — the `## Surface` ↔ `src/core` and `src/server` bijection (value + type exports), the `OllamaProvider`, `OllamaJudge`, and `
|
|
884
|
+
- [`tests/guides.test.ts`](../tests/guides.test.ts) — the `## Surface` ↔ `src/core` and `src/server` bijection (value + type exports), the `OllamaProvider`, `OllamaJudge`, `OllamaDaemonInterface`, and `OllamaFixtureInterface` method bijections, and the equality gate: every `Summary` cell against its declaration's description paragraph, each titled fence — `Ask Mica a noul` and `createOllama + generate` — against the `@example` block of that title, with `Ask Mica a noul` pinned so the titled pair cannot be retired silently, and the README pitch against this guide's tagline. It also runs the flagship fences and asserts the values they log. Of the server face's fences, it runs the declaration refusal, the model digest comparison, and the retained unload reply, none of which starts a process, and never runs the dedicated daemon fence, which starts a real executable. It extracts each streaming fence from the README and from this guide and executes it, with its real imports and a global `fetch` the test replaces, over the turns the fence handles: this guide's over a plain, a reclassified, a cancelled, and a refused turn, and the README's, which has no `catch` arm, over the plain and the reclassified turn. It asserts the logged values, the deltas, the fence's message list, the whole body of each request, and the error the fence throws.
|
|
853
885
|
- [`tests/src/core/OllamaProvider.test.ts`](../tests/src/core/OllamaProvider.test.ts) — hermetic provider request-shape (including the default `truncate` key and the opt-in `shift` key), options, framing, transport-seam, abort, deadline, and unreachable-upstream coverage, the wire refusals — an in-band error, another model, a model load, a malformed record, empty `messages`, a stream cut before `done`, and the context remedy — plus the streaming fold — deltas, tool-call accumulation, done-line usage, the `done_reason: 'length'` truncation and its stray-reason refusals, the unterminated tail flush, and think separation — driven over a canned NDJSON transport. Its recording proxy uses a deliberately unreachable default and asserts only captured requests and local provider behavior.
|
|
854
886
|
- [`tests/src/core/helpers.test.ts`](../tests/src/core/helpers.test.ts) — the wire leaves: the request projection with its control-token escape and every response extraction, including each malformed-wire refusal, the `done_reason` reader's `'length'`, other-reason, missing, and non-string cases, and the terminal timing reader's verbatim nanoseconds, zero, absent, malformed, and `done` cases.
|
|
855
887
|
- [`tests/src/core/factories.test.ts`](../tests/src/core/factories.test.ts) — hermetic `createOllama` shape, identity, defaults, passthrough, and unreachable-upstream coverage.
|
|
856
|
-
- [`tests/src/core/integration.test.ts`](../tests/src/core/integration.test.ts) — the `src/core` integration scope. A real `@orkestrel/server` + `@orkestrel/router` relay in front of this provider carries ordered content and thinking deltas, tools, and usage while keeping the browser and daemon credentials apart, refuses a wrong bearer with an empty `401` before the daemon transport is entered, crosses a browser cancel and a server deadline as an abort frame with its partial, reduces a daemon stream failure to the fixed public error frame, and replays a returned tool call. Beside those, a real agent over a canned NDJSON stream reports the model, meter, and budget layers in `result.stop`, and hermetic context framing,
|
|
857
|
-
- [`tests/setup.test.ts`](../tests/setup.test.ts) — the shared host-independent test infrastructure, over the conversation padding, the
|
|
888
|
+
- [`tests/src/core/integration.test.ts`](../tests/src/core/integration.test.ts) — the `src/core` integration scope. A real `@orkestrel/server` + `@orkestrel/router` relay in front of this provider carries ordered content and thinking deltas, tools, and usage while keeping the browser and daemon credentials apart, refuses a wrong bearer with an empty `401` before the daemon transport is entered, crosses a browser cancel and a server deadline as an abort frame with its partial, reduces a daemon stream failure to the fixed public error frame, and replays a returned tool call. Beside those, a real agent over a canned NDJSON stream reports the model, meter, and budget layers in `result.stop`, and hermetic context framing, reference, cherry-pick, canonical assembly order, scope allow-lists, workspace injection, and conversation selection run through the unreachable recording proxy, with a compile-time drift gate asserting the wire request and response shapes stay compatible with the official `ollama` client's types; that gate's authoritative check is `npm run check` (root tsc), while its run under vitest is an incidental no-op (`expectTypeOf` performs no runtime assertions).
|
|
889
|
+
- [`tests/setup.test.ts`](../tests/setup.test.ts) — the shared host-independent test infrastructure, over the conversation padding, the workspace seeder, and the `PAGE_TOOL` definition `tests/setup.ts` exports, and over the host-independent half of `tests/setupServer.ts`: its request-narrowing guards, its refusing and streaming transports, its tool fixtures, its scripted agent stream and agent-stream driver, and its environment readers.
|
|
858
890
|
- [`tests/setupServer.test.ts`](../tests/setupServer.test.ts) — the Node-resource half of `tests/setupServer.ts`: the daemon fixtures the `src:server` proofs use — the fake daemon declarations built without starting a child, and the in-process peer that answers the metadata and unload routes and records each request's exact bytes — the recording proxy and the relay server on real loopback sockets, the captured and open transports, whose fixtures answer in memory, the capture wait, the provider-stream driver, the wire tables `WEATHER_TOOL` and the insatiable tool's chunk line, and the page fixture's Node half — the request recorder the relay server and the page fixture share, the derived import map, the served document's presence guards, the contained file route, the control route, the port reservation, the membership the page bounds declare — the attempt allowance, the release share beside it, the per-call shares spent inside them, the case bound that contains the pair, and the launch count the retry spends — the ordering the live controls' own intervals hold, the attempt deadline's own expiry error, the elapsed completion a bounded attempt reports on each interleaving that can outlast it (an acquisition that never settles, one that settles inside the release share, a release that parks past that share, and a release that crossed the allowance), each of those measured against the deadlines it had to wait out plus one named scheduling allowance, so what the case proves is timer-bounded completion rather than a nominal sum, the failure each of them keeps reachable as its cause — the attempt's own failure under a composed strand, and the deadline's `TimeoutError` under a crossed release — the reading each thrown failure carries into a composed message, the decision the bounded retry's predicate makes over an inert attempt record, including the interrupted run it refuses, the release order a real fixture takes when the release after it rejects, the evaluate boundary's narrowing and the deadline it carries, the guards that narrow what the page reports back, the live page proof's browser and build gates — a host with no browser and a tree with no build — the scenarios that capture the first request a provider sends through a recording proxy, each ending the call by aborting it, awaiting it, or leaving it open, the readers and runners that measure a packed package, proved against a dependency-free fixture package and a loopback registry that answers only `ping`, and the guard that keeps every hermetic project from importing `tests/setupService.ts`, which contacts the daemon when it loads: it takes the projects from `vite.config.ts`, follows every import form to a fixed point, and refuses the module as a setup file. It compares the files that references and setup paths resolve to, never their spelling, so a backslash separator, a letter case the host folds, and a query after the path cannot hide the module, while a `?raw` or `?url` import stays an asset. It refuses a `new URL(…, import.meta.url)` built at run time as it refuses a computed `import()`, apart from `vite.config.ts`, whose computed URL is inspected and listed.
|
|
859
891
|
- [`tests/setupService.test.ts`](../tests/setupService.test.ts) — the hermetic half of the `service` project's setup: the environment readers, the sampling tables, the readiness contract, and the live page gate's refusal of an origin the daemon refuses.
|
|
860
892
|
- [`tests/conformance.test.ts`](../tests/conformance.test.ts) — where this package's wire types drift from the official `ollama` client they are written against.
|
|
@@ -868,7 +900,7 @@ The hermetic projects — `src:core`, `src:server`, `setup`, `guides`, `conforma
|
|
|
868
900
|
- [`tests/service/tools.test.ts`](../tests/service/tools.test.ts) and [`tests/service/authority.test.ts`](../tests/service/authority.test.ts) — live tool dispatch through the agent loop, and the authority gate's approval and denial paths.
|
|
869
901
|
- [`tests/service/budget.test.ts`](../tests/service/budget.test.ts) and [`tests/service/lifecycle.test.ts`](../tests/service/lifecycle.test.ts) — live token-budget enforcement on the reported usage, the meter layer's mid-stream trip under `allowance: budget`, the daemon's `done_reason: 'length'` at a `num_predict` cap with its `result.truncated` and model-layer `stop`, and the agent's status, event, and abort lifecycle.
|
|
870
902
|
- [`tests/service/schema.test.ts`](../tests/service/schema.test.ts) and [`tests/service/scopes.test.ts`](../tests/service/scopes.test.ts) — a live structured-output `schema` constraining the answer, and a live scope filtering what reaches the wire.
|
|
871
|
-
- [`tests/service/
|
|
903
|
+
- [`tests/service/conversation.test.ts`](../tests/service/conversation.test.ts) — long-conversation instruction behavior, with proxy calls explicitly forwarding to `OLLAMA_CONFIG.host`.
|
|
872
904
|
|
|
873
905
|
## See also
|
|
874
906
|
|