@orkestrel/scaffold 0.0.123 → 0.0.125
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/agents/skills/orkestrel-publish/scripts/steps.js +523 -0
- package/dist/agents/skills/orkestrel-publish/scripts/wave.js +70 -11
- package/dist/bin/main.js +18 -18
- package/dist/bin/main.js.map +1 -1
- package/dist/host/agents/orchestration.md +5 -1
- package/dist/host/agents/platforms/windows.md +9 -1
- package/dist/host/agents/skills/orkestrel-dispatch/SKILL.md +1 -1
- package/dist/host/agents/skills/orkestrel-falsify/references/brief.md +1 -0
- package/dist/host/agents/skills/orkestrel-harden/references/methods.md +30 -2
- package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +1 -0
- package/dist/host/agents/skills/orkestrel-parallel/references/t3.md +5 -1
- package/dist/host/agents/skills/orkestrel-publish/SKILL.md +1 -0
- package/dist/host/agents/skills/orkestrel-publish/references/release.md +2 -2
- package/dist/host/agents/skills/orkestrel-publish/references/wave.md +23 -6
- package/dist/host/agents/skills/orkestrel-publish/scripts/steps.ts +654 -0
- package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +79 -14
- package/dist/host/claude/agents/orkestrel.md +45 -45
- package/dist/host/claude/rules/patterns.md +1 -1
- package/dist/host/claude/rules/portability.md +2 -0
- package/dist/host/claude/rules/quality.md +3 -1
- package/dist/host/claude/rules/tests.md +3 -1
- package/dist/host/guides/agent.md +349 -244
- package/dist/host/guides/brief.md +52 -48
- package/dist/host/guides/browser.md +2 -2
- package/dist/host/guides/contract.md +226 -104
- package/dist/host/guides/database.md +12 -12
- package/dist/host/guides/interpret.md +531 -155
- package/dist/host/guides/mcp.md +183 -61
- package/dist/host/guides/ndjson.md +47 -34
- package/dist/host/guides/ollama.md +123 -66
- package/dist/host/guides/program.md +117 -39
- package/dist/host/guides/qualifier.md +110 -59
- package/dist/host/guides/rater.md +85 -32
- package/dist/host/guides/reason.md +377 -114
- package/dist/host/guides/scaffold.md +20 -12
- package/dist/host/guides/study.md +580 -483
- package/dist/host/guides/tool.md +163 -58
- package/dist/host/guides/toolbox.md +159 -80
- package/dist/host/guides/workflow.md +44 -25
- package/dist/host/manifest.json +41 -35
- package/dist/src/core/index.cjs +17 -17
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.js +17 -17
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +23 -11
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +10 -6
- package/dist/src/server/index.d.ts +10 -6
- package/dist/src/server/index.js +23 -11
- package/dist/src/server/index.js.map +1 -1
- package/package.json +17 -17
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
|
|
6
6
|
The package supplies a chat provider wire on the `/api/chat` path and a raw judge wire for Mica on the `/api/generate` path. The `OllamaProvider` class extends the `AgentProvider` engine for chat generation and streaming. The `OllamaJudge` class extends the `AgentJudge` engine for calibrated candidate probabilities. The shared engines own deadlines, transport, headers, and result assembly; see [Agent](agent.md) for their contracts. The server face, `@orkestrel/ollama/server`, owns a dedicated daemon session in Node: it starts a declared Ollama executable on a dedicated loopback port, verifies the executable's version and every declared model digest, unloads the declared models, and stops the process tree it started; see [Daemon session](#daemon-session).
|
|
7
7
|
|
|
8
|
-
The design is deliberately spare — an external boundary kept honest. Every `unknown` wire value is narrowed through the `@orkestrel/contract` guards (`isRecord`, `isString
|
|
8
|
+
The design is deliberately spare — an external boundary kept honest. Every `unknown` wire value is narrowed through the `@orkestrel/contract` guards (`isRecord`, `isString`) rather than a type assertion. A field the record leaves out reads as absent (empty content, no usage), and a field that is present and malformed refuses as `ProviderError` `'PROTOCOL'`. Every provider call streams: the request always carries `stream: true`, and `generate` drains the same NDJSON path `stream` exposes, so neither call can report content the other would not. The wire `think` flag is configurable through `OllamaOptions.think` (default `false`) and overrideable per call through `ProviderStreamOptions.think`; with `think: true` the daemon returns reasoning on the separate `message.thinking` channel, streamed live as `thinking` deltas. Either way the base's splitter separates any `<think>` span the daemon inlines anyway, so the assembled `content` is clean and the reasoning surfaces as `ProviderResult.thinking`. The agent records that reasoning on the assistant message. The provider's `replay` policy filters stored reasoning at the provider input boundary; the Ollama request mapper omits that reasoning from the wire. A per-call `ProviderStreamOptions.schema` (a JSON schema object, from `@orkestrel/agent`) forwards verbatim as the wire's structured-output `format` field, and is omitted from the request when no schema is supplied. `OllamaOptions.truncate` defaults to `false` and rides every body, so a prompt over the context window refuses instead of losing its earlier turns, and `OllamaOptions.shift` is sent only when set; see [A prompt over the context window](#a-prompt-over-the-context-window). Token usage reuses the `TokenUsage` shape rather than minting its own.
|
|
9
9
|
|
|
10
10
|
The dependency is strictly one-way: this surface imports the base and the contract types from `@orkestrel/agent` and reaches errors through that base, the parser factory from `@orkestrel/ndjson`, tool-call shapes from `@orkestrel/tool`, the usage shape from `@orkestrel/budget`, and the guards from `@orkestrel/contract` — those packages never import from here. The package publishes two faces. The core face, `@orkestrel/ollama`, is built from `src/core`, which reaches no `node:*` module and no DOM global, so the same build serves a server process and a browser page. The server face, `@orkestrel/ollama/server`, is built from `src/server` and runs in Node only: it imports Node modules, the process session from `@orkestrel/process`, the emitter from `@orkestrel/emitter`, the guards from `@orkestrel/contract`, and the terminal timing reader from the core face, and nothing in `src/core` imports it. The core face is tested live against `qwen3.5:4b-q4_K_M` in a dedicated `service` test project that requires the daemon and warms the model first, with no `skipIf`, while the `src:core` project stays hermetic on canned-transport and recording-proxy assertions that pass with the daemon down. Source: [`src/core`](../src/core), surfaced through the `@orkestrel/ollama` barrel and aliased `@src/core` inside this repo, and [`src/server`](../src/server), surfaced through the `@orkestrel/ollama/server` barrel and aliased `@src/server`.
|
|
11
11
|
|
|
@@ -72,29 +72,48 @@ Pass `tools` (a non-empty `ToolDefinition[]` from `@orkestrel/tool`) to advertis
|
|
|
72
72
|
|
|
73
73
|
### Surface
|
|
74
74
|
|
|
75
|
-
| Name | Kind | Signature
|
|
76
|
-
| -------------------- | --------- |
|
|
77
|
-
| `createOllama` | function | `(options: OllamaOptions) => ProviderInterface`
|
|
78
|
-
| `OllamaProvider` | class | `new (options: OllamaOptions) => AgentProviderInterface`
|
|
79
|
-
| `OllamaOptions` | interface | `{ model, url?, keepAlive?, options?, think?, truncate?, shift? }`
|
|
80
|
-
| `WireChatRequest` | interface | `{ model, messages, stream, keep_alive, think, options?, tools?, format?, truncate
|
|
81
|
-
| `OllamaDurations` | interface | `{ total, load, prompt, decode }`
|
|
82
|
-
| `OllamaCounts` | interface | `{ prompt, decode, cached }`
|
|
83
|
-
| `OllamaTiming` | interface | `{ durations, counts, invalid }`
|
|
84
|
-
| `DEFAULT_OLLAMA_URL` | const | `"http://localhost:11434"`
|
|
85
|
-
| `DEFAULT_KEEP_ALIVE` | const | `"5m"`
|
|
86
|
-
| `OLLAMA_CHAT_PATH` | const | `"/api/chat"`
|
|
87
|
-
| `mapMessages` | function | `(messages: readonly Message[]) => WireChatRequest['messages']`
|
|
88
|
-
| `extractContent` | function | `(record: Readonly<Record<string, unknown>>) => string`
|
|
89
|
-
| `extractThinking` | function | `(record: Readonly<Record<string, unknown>>) => string`
|
|
90
|
-
| `extractUsage` | function | `(record: Readonly<Record<string, unknown>>) => TokenUsage \| undefined`
|
|
91
|
-
| `extractTruncated` | function | `(record: Readonly<Record<string, unknown>>) => true \| undefined`
|
|
92
|
-
| `extractTiming` | function | `(record: Readonly<Record<string, unknown>>) => OllamaTiming \| undefined`
|
|
93
|
-
| `extractTools` | function | `(record: Readonly<Record<string, unknown>>) => readonly ToolCall[]`
|
|
94
|
-
| `extractArguments` | function | `(value: unknown) => Readonly<Record<string, unknown>>`
|
|
75
|
+
| Name | Kind | Signature | Summary |
|
|
76
|
+
| -------------------- | --------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
77
|
+
| `createOllama` | function | `(options: OllamaOptions) => ProviderInterface` | Creates a local Ollama inference provider — a `ProviderInterface` over the daemon's `POST /api/chat`, assembling `generate` from the same NDJSON engine as `stream`. |
|
|
78
|
+
| `OllamaProvider` | class | `new (options: OllamaOptions) => AgentProviderInterface` | Implements the Ollama `/api/chat` wire over the shared `AgentProvider` engine. |
|
|
79
|
+
| `OllamaOptions` | interface | `{ model, url?, keepAlive?, options?, think?, truncate?, shift? }` | Represents the configuration `createOllama` accepts for the local Ollama backend. |
|
|
80
|
+
| `WireChatRequest` | interface | `{ model, messages, stream, keep_alive, think, options?, tools?, format?, truncate, shift? }` | Represents the exact `POST /api/chat` request body `OllamaProvider` sends — the internal typed wire contract. |
|
|
81
|
+
| `OllamaDurations` | interface | `{ total, load, prompt, decode }` | Carries the daemon durations of one terminal record in raw nanoseconds. |
|
|
82
|
+
| `OllamaCounts` | interface | `{ prompt, decode, cached }` | Carries the token counts of one terminal record. |
|
|
83
|
+
| `OllamaTiming` | interface | `{ durations, counts, invalid }` | Carries the timing observation of one terminal record. |
|
|
84
|
+
| `DEFAULT_OLLAMA_URL` | const | `"http://localhost:11434"` | Names the local Ollama daemon base URL, `'http://localhost:11434'`, assumed when `OllamaOptions.url` is omitted. |
|
|
85
|
+
| `DEFAULT_KEEP_ALIVE` | const | `"5m"` | Names how long the model stays resident after a call — `'5m'` when `OllamaOptions.keepAlive` is omitted, Ollama's own `keep_alive` default, expressed as a duration string. |
|
|
86
|
+
| `OLLAMA_CHAT_PATH` | const | `"/api/chat"` | Names the Ollama chat endpoint appended to the configured base URL. |
|
|
87
|
+
| `mapMessages` | function | `(messages: readonly Message[]) => WireChatRequest['messages']` | Maps conversation turns onto the `/api/chat` wire's minimal message shape, escaping each listed control token in message content, call names, and top-level arguments. |
|
|
88
|
+
| `extractContent` | function | `(record: Readonly<Record<string, unknown>>) => string` | Extracts the assistant text of one wire record. |
|
|
89
|
+
| `extractThinking` | function | `(record: Readonly<Record<string, unknown>>) => string` | Extracts the daemon-side reasoning of one wire record. |
|
|
90
|
+
| `extractUsage` | function | `(record: Readonly<Record<string, unknown>>) => TokenUsage \| undefined` | Extracts the token usage of one wire record. |
|
|
91
|
+
| `extractTruncated` | function | `(record: Readonly<Record<string, unknown>>) => true \| undefined` | Extracts whether one terminal wire record reports that the model ended its answer at its own token limit. |
|
|
92
|
+
| `extractTiming` | function | `(record: Readonly<Record<string, unknown>>) => OllamaTiming \| undefined` | Extracts the daemon timing of one terminal wire record. |
|
|
93
|
+
| `extractTools` | function | `(record: Readonly<Record<string, unknown>>) => readonly ToolCall[]` | Extracts the tool calls of one wire record's `message.tool_calls`. |
|
|
94
|
+
| `extractArguments` | function | `(value: unknown) => Readonly<Record<string, unknown>>` | Extracts a wire `arguments` value as a record. |
|
|
95
95
|
|
|
96
96
|
`OllamaOptions` extends `ProviderOptions`, so a caller also passes the base's own keys through it: `timeout` (the per-call deadline), `fetch` (the transport), `headers` (the per-request header hook), and `replay` (the stored-thinking policy). [`agent.md`](agent.md) states each one.
|
|
97
97
|
|
|
98
|
+
Beside those rows, the core face exports what the constructors and the leaves compose.
|
|
99
|
+
|
|
100
|
+
| Name | Kind | Signature | Summary |
|
|
101
|
+
| ----------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
|
|
102
|
+
| `ollamaOptionsShape` | const | `import("@orkestrel/contract").ObjectShape<{ model: import("@orkestrel/contract").StringShape; 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>>; think: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").BooleanShape>; truncate: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").BooleanShape>; shift: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").BooleanShape>; timeout: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; replay: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").LiteralShape<readonly ["none", "turn", "all"]>>; }, false>` | Describes the serializable part of `OllamaOptions`, the record a provider's constructor checks exactly. |
|
|
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
|
+
| `ollamaOptionsContract` | const | `ContractInterface<unknown>` | Holds the compiled contract a provider's constructor checks its serializable options against. |
|
|
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; set AgentOptions.window to fold the conversation, 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
|
+
| `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
|
+
| `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
|
+
| `matchesContextRefusal` | function | `(text: string) => boolean` | Checks whether a daemon's refusal text names the context window. |
|
|
110
|
+
| `renderDaemonFailure` | function | `(failure: unknown) => string` | Renders a daemon's in-band `error` value as refusal text, bounded like an HTTP error excerpt. |
|
|
111
|
+
| `readMessage` | function | `(record: Readonly<Record<string, unknown>>) => Readonly<Record<string, unknown>> \| undefined` | Reads a record's `message`, which a record may omit. |
|
|
112
|
+
| `readMessageText` | function | `(record: Readonly<Record<string, unknown>>, key: string) => string` | Reads one text field of a record's `message`, which a record may omit. |
|
|
113
|
+
| `readUsageCount` | function | `(record: Readonly<Record<string, unknown>>, key: string) => number \| undefined` | Reads one token count of a record, which a record may omit. |
|
|
114
|
+
| `matchesCandidateName` | function | `(key: string, label: string \| undefined) => boolean` | Checks whether a choice key renders as a candidate name rather than as a position. |
|
|
115
|
+
| `matchesCriterionText` | function | `(question: JudgeQuestion) => boolean` | Checks whether a question's criteria give the model anything to read: a description, or a choice's name. |
|
|
116
|
+
|
|
98
117
|
The wire leaves — `mapMessages` and the `extract*` narrowing set — are the pure request projection and response extractions `OllamaProvider` composes. They are exported and unit-tested on their own so the package's highest-risk code, the boundary narrowing of every wire `unknown` through the `@orkestrel/contract` guards, is provable without a daemon. Everything they do not do lives in `@orkestrel/agent`: the deadline, the transport seam, the streaming spine, the splitter, and the assembly of a `ProviderResult`.
|
|
99
118
|
|
|
100
119
|
`mapMessages` escapes the tokens `MICA_SPECIAL_TOKENS` lists, the list Mica's judge prompt also uses, on every role, the host's `system` text included: message content, a replayed call's name, and each top-level argument key and string value. `escapeSpecialTokens` inserts U+200B after each listed token's opening `<`, so a request holding no listed token keeps its bytes. A nested argument, a tool definition, `format`, `options`, `images`, and `model` stay as given. So when a tool's name spells a listed token, its replayed call reads apart from its definition, and a model that copies the replay names no tool. Two keys of one argument object that differ only by the escape collapse to one in the request, and the last value wins. Stored messages and the call a tool ran with keep their text.
|
|
@@ -110,8 +129,8 @@ The raw judge exports the following declarations.
|
|
|
110
129
|
| Name | Kind | Signature | Summary |
|
|
111
130
|
| ---------------------- | --------- | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
112
131
|
| `OllamaJudge` | class | `new (options: OllamaJudgeOptions) => AgentJudgeInterface` | Implements Mica's raw Ollama logprob wire over the shared judge engine. |
|
|
113
|
-
| `OllamaJudgeOptions` | interface | `{ model, system, calibration?, url?, keepAlive?, options? }`
|
|
114
|
-
| `WireGenerateRequest` | interface | `{ model, prompt, raw, stream, logprobs, top_logprobs, keep_alive, options }`
|
|
132
|
+
| `OllamaJudgeOptions` | interface | `{ model, system, calibration?, url?, keepAlive?, options?, truncate? }` | Configures the raw Mica judge wire, its calibration, and its transport. |
|
|
133
|
+
| `WireGenerateRequest` | interface | `{ model, prompt, raw, stream, logprobs, top_logprobs, keep_alive, options, truncate }` | Transliterates the Ollama raw, non-streaming `POST /api/generate` request. |
|
|
115
134
|
| `Logprob` | interface | `{ token, logprob }` | Carries a token and its log probability from Ollama's top logprob list. |
|
|
116
135
|
| `createOllamaJudge` | function | `(options: OllamaJudgeOptions) => JudgeInterface` | Creates a Mica judge that reads calibrated candidate probabilities from raw Ollama logprobs. |
|
|
117
136
|
| `escapeSpecialTokens` | function | `(text: string) => string` | Escapes each listed control token by inserting U+200B after its opening angle bracket. |
|
|
@@ -130,22 +149,27 @@ The raw judge exports the following declarations.
|
|
|
130
149
|
|
|
131
150
|
The server face, `@orkestrel/ollama/server`, exports the following daemon session declarations. It runs in Node only; [Daemon session](#daemon-session) states the lifecycle these declarations carry.
|
|
132
151
|
|
|
133
|
-
| Name | Kind | Signature
|
|
134
|
-
| ------------------------- | --------- |
|
|
135
|
-
| `createOllamaDaemon` | function | `(options: OllamaDaemonOptions) => OllamaDaemonInterface`
|
|
136
|
-
| `OllamaDaemon` | class | `new (options: OllamaDaemonOptions) => OllamaDaemonInterface`
|
|
137
|
-
| `OllamaDaemonInterface` | interface | `{ url, identity, maintenance, emitter, start(), unload(), stop(), destroy() }`
|
|
138
|
-
| `OllamaDaemonOptions` | interface | `{ on?, error?, executable, url, models, workspace, environment?, store?, readiness?, metadata?, termination?, signal? }`
|
|
139
|
-
| `OllamaExecutable` | interface | `{ path, digest, version, arguments? }`
|
|
140
|
-
| `OllamaModel` | interface | `{ name, digest }`
|
|
141
|
-
| `OllamaMetadataOptions` | interface | `{ timeout?, bytes? }`
|
|
142
|
-
| `OllamaDaemonIdentity` | interface | `{ executable, url, pid, models }`
|
|
143
|
-
| `OllamaBytes` | interface | `{ content, size, digest, complete }`
|
|
144
|
-
| `OllamaMaintenance` | interface | `{ sequence, model, url, request, response?, status?, timing?, error? }`
|
|
145
|
-
| `OllamaDaemonEventMap` | type | `{ readonly start: readonly [identity: OllamaDaemonIdentity]; readonly unload: readonly [maintenance: OllamaMaintenance]; readonly stop: readonly [confirmed: boolean]; readonly error: readonly [error: unknown]; }`
|
|
146
|
-
| `
|
|
147
|
-
| `
|
|
148
|
-
| `
|
|
152
|
+
| Name | Kind | Signature | Summary |
|
|
153
|
+
| ------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
|
|
154
|
+
| `createOllamaDaemon` | function | `(options: OllamaDaemonOptions) => OllamaDaemonInterface` | Creates an unstarted daemon with a snapshot of the caller's declaration and lifecycle hooks. |
|
|
155
|
+
| `OllamaDaemon` | class | `new (options: OllamaDaemonOptions) => OllamaDaemonInterface` | Owns a dedicated daemon through verified startup, declared maintenance, and permanent cleanup. |
|
|
156
|
+
| `OllamaDaemonInterface` | interface | `{ url, identity, maintenance, emitter, start(), unload(), stop(), destroy() }` | Owns a dedicated daemon from validated startup through declared-model maintenance and stop. |
|
|
157
|
+
| `OllamaDaemonOptions` | interface | `{ on?, error?, executable, url, models, workspace, environment?, store?, readiness?, metadata?, termination?, signal? }` | Configures a dedicated daemon with explicit executable, endpoint, and model declarations. |
|
|
158
|
+
| `OllamaExecutable` | interface | `{ path, digest, version, arguments? }` | Declares the executable identity required before a daemon starts. |
|
|
159
|
+
| `OllamaModel` | interface | `{ name, digest }` | Declares a model name and the digest its inventory entry must report. |
|
|
160
|
+
| `OllamaMetadataOptions` | interface | `{ timeout?, bytes? }` | Bounds each metadata or unload response independently of the startup deadline. |
|
|
161
|
+
| `OllamaDaemonIdentity` | interface | `{ executable, url, pid, models }` | Records the executable, endpoint, root process, and model identities verified at startup. |
|
|
162
|
+
| `OllamaBytes` | interface | `{ content, size, digest, complete }` | Preserves a bounded HTTP body as base64 with its byte count and SHA-256 digest. |
|
|
163
|
+
| `OllamaMaintenance` | interface | `{ sequence, model, url, request, response?, status?, timing?, error? }` | Records one declared model's unload request and the response observed for that attempt. |
|
|
164
|
+
| `OllamaDaemonEventMap` | type | `{ readonly start: readonly [identity: OllamaDaemonIdentity]; readonly unload: readonly [maintenance: OllamaMaintenance]; readonly stop: readonly [confirmed: boolean]; readonly error: readonly [error: unknown]; }` | Reports verified startup, recorded unloads, permanent stop, and daemon failures. |
|
|
165
|
+
| `ollamaDaemonShape` | const | `import("@orkestrel/contract").ObjectShape<{ executable: import("@orkestrel/contract").ObjectShape<{ path: import("@orkestrel/contract").StringShape; digest: import("@orkestrel/contract").StringShape; version: import("@orkestrel/contract").StringShape; arguments: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").StringShape>>; }, boolean \| import("@orkestrel/contract").ContractShape>; url: import("@orkestrel/contract").StringShape; models: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ name: import("@orkestrel/contract").StringShape; digest: import("@orkestrel/contract").StringShape; }, boolean \| import("@orkestrel/contract").ContractShape>>; workspace: import("@orkestrel/contract").StringShape; environment: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").ObjectShape<Record<never, never>, import("@orkestrel/contract").StringShape>>; store: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; readiness: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; metadata: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").ObjectShape<{ timeout: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; bytes: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; }, boolean \| import("@orkestrel/contract").ContractShape>>; termination: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").ObjectShape<{ grace: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; drain: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; }, boolean \| import("@orkestrel/contract").ContractShape>>; }, false>` | Describes the serializable part of `OllamaDaemonOptions`, the record whose audit names a refused declaration's faults by path. |
|
|
166
|
+
| `ollamaDaemonContract` | const | `ContractInterface<unknown>` | Holds the compiled contract whose audit names a refused daemon declaration's faults by path. |
|
|
167
|
+
| `OLLAMA_TIMER_LIMIT` | const | `2147483647` | Bounds a daemon duration to 2147483647 milliseconds, the longest a Node timer holds. |
|
|
168
|
+
| `OLLAMA_DAEMON_LIVE` | const | `readonly string[]` | Lists the keys of a daemon declaration that hold live values, which no shape declares. |
|
|
169
|
+
| `OLLAMA_DAEMON_KEYS` | const | `Readonly<{ daemon: readonly string[]; executable: readonly string[]; model: readonly string[]; metadata: readonly string[]; termination: readonly string[]; }>` | Lists the keys each record of a daemon declaration admits, live values included. |
|
|
170
|
+
| `OLLAMA_READINESS` | const | `60000` | Bounds startup through version and model verification to 60000 milliseconds by default. |
|
|
171
|
+
| `OLLAMA_METADATA_TIMEOUT` | const | `10000` | Bounds each metadata or unload request and body read to 10000 milliseconds by default. |
|
|
172
|
+
| `OLLAMA_METADATA_BYTES` | const | `1048576` | Bounds each retained metadata or unload response to 1048576 bytes by default. |
|
|
149
173
|
|
|
150
174
|
The server face reports every refusal as one branded error class.
|
|
151
175
|
|
|
@@ -153,7 +177,7 @@ The server face reports every refusal as one branded error class.
|
|
|
153
177
|
| -------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
|
|
154
178
|
| `OllamaError` | class | `new (message: string, options: OllamaErrorOptions) => OllamaError` | Carries a daemon refusal with a machine-readable category, observations, and original cause. |
|
|
155
179
|
| `OllamaErrorOptions` | interface | `{ code, context?, cause? }` | Configures a daemon refusal with its category, observations, and original cause. |
|
|
156
|
-
| `OllamaErrorContext` | interface | `{ operation?, path?, url?, model?, expected?, received?, evidence? }`
|
|
180
|
+
| `OllamaErrorContext` | interface | `{ operation?, path?, url?, model?, expected?, received?, evidence?, faults? }` | Carries the operation and identity observations accompanying a daemon refusal. |
|
|
157
181
|
| `OllamaErrorCode` | type | `(typeof OLLAMA_ERROR_CODES)[number]` | Defines the machine-readable refusal categories of the daemon lifecycle. |
|
|
158
182
|
| `OLLAMA_ERROR_CODES` | const | `readonly ["invalid", "occupied", "digest", "spawn", "readiness", "version", "model", "owner", "metadata", "unload", "cleanup", "aborted", "state"]` | Lists every machine-readable daemon refusal category. |
|
|
159
183
|
| `OLLAMA_ERROR_BRAND` | const | `unique symbol` | Identifies daemon errors across installations and module formats through the global symbol registry. |
|
|
@@ -166,6 +190,7 @@ The session composes the following validators and protocol helpers, each exporte
|
|
|
166
190
|
| `isOllamaDaemonOptions` | function | `(value: unknown) => value is OllamaDaemonOptions` | Checks whether an unknown declaration can safely reach daemon preflight. |
|
|
167
191
|
| `isOllamaExecutable` | function | `(value: unknown) => value is OllamaExecutable` | Checks whether a value declares an absolute executable and its offline identity. |
|
|
168
192
|
| `isOllamaModel` | function | `(value: unknown) => value is OllamaModel` | Checks whether a value declares an exact model name and inventory digest. |
|
|
193
|
+
| `matchesDeclaredKeys` | function | `(value: Readonly<Record<string, unknown>>, keys: readonly string[]) => boolean` | Checks whether every key of a record is one the declaration names. |
|
|
169
194
|
| `isOllamaOrigin` | function | `(value: unknown) => value is string` | Checks whether a string selects an explicit dedicated HTTP loopback origin. |
|
|
170
195
|
| `buildOllamaEnvironment` | function | `(inherited: Readonly<Record<string, string \| undefined>>, environment: Readonly<Record<string, string \| undefined>> \| undefined, url: string, store?: string) => Readonly<Record<string, string \| undefined>>` | Builds the environment with dedicated values overriding every inherited or caller casing. |
|
|
171
196
|
| `matchesOllamaAnnouncement` | function | `(line: string, url: string) => boolean` | Checks whether stderr announces the dedicated loopback listener. |
|
|
@@ -185,7 +210,7 @@ Each following table lists the methods one class or interface declares. The wire
|
|
|
185
210
|
|
|
186
211
|
#### `OllamaProvider`
|
|
187
212
|
|
|
188
|
-
The `frame` method opens the call's framing state and the `finish` method drains it; the `encode` method writes the request and the `read` method reads one record back.
|
|
213
|
+
The `frame` method opens the call's framing state and the `finish` method drains it; the `encode` method writes the request and the `read` method reads one record back. The class also overrides the inherited `stream` method, which appends `OLLAMA_CONTEXT_REMEDY` to a 400 that names the context window.
|
|
189
214
|
|
|
190
215
|
| Method | Returns | Summary |
|
|
191
216
|
| -------- | -------------------------------------------------- | -------------------------------------------------------------------------------------- |
|
|
@@ -196,7 +221,7 @@ The `frame` method opens the call's framing state and the `finish` method drains
|
|
|
196
221
|
|
|
197
222
|
#### `OllamaJudge`
|
|
198
223
|
|
|
199
|
-
The engine calls these seams for each question. Call the inherited `ask` method to validate the full request, issue the calls, and merge their answers and usage.
|
|
224
|
+
The engine calls these seams for each question. Call the inherited `ask` method to validate the full request, issue the calls, and merge their answers and usage. The class overrides that method only to append `OLLAMA_JUDGE_CONTEXT_REMEDY` to a 400 that names the context window.
|
|
200
225
|
|
|
201
226
|
| Method | Returns | Summary |
|
|
202
227
|
| -------- | --------------------- | --------------------------------------------------------------------------- |
|
|
@@ -219,30 +244,32 @@ A caller drives these methods directly, in the order [Daemon session](#daemon-se
|
|
|
219
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 server face'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.
|
|
220
245
|
|
|
221
246
|
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.
|
|
222
|
-
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`
|
|
223
|
-
3. **The `/api/chat` wire body.** `OllamaProvider` POSTs to `${url}${OLLAMA_CHAT_PATH}`, defaulting `url` to `DEFAULT_OLLAMA_URL` and `keep_alive` to `DEFAULT_KEEP_ALIVE`. The body carries `model`, the mapped `messages`, `stream: true` on every provider call, `keep_alive`, and `think` (the per-call `ProviderStreamOptions.think` override when present, else `OllamaOptions.think`, default `false`), adding `options` only when configured, `format` only when the call supplies a `ProviderStreamOptions.schema`, and `tools` only when a non-empty `ToolDefinition[]` is passed. The top-level `truncate`
|
|
247
|
+
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.
|
|
248
|
+
3. **The `/api/chat` wire body.** `OllamaProvider` POSTs to `${url}${OLLAMA_CHAT_PATH}`, defaulting `url` to `DEFAULT_OLLAMA_URL` and `keep_alive` to `DEFAULT_KEEP_ALIVE`. The body carries `model`, the mapped `messages`, `stream: true` on every provider call, `keep_alive`, and `think` (the per-call `ProviderStreamOptions.think` override when present, else `OllamaOptions.think`, default `false`), adding `options` only when configured, `format` only when the call supplies a `ProviderStreamOptions.schema`, and `tools` only when a non-empty `ToolDefinition[]` is passed. The top-level `truncate` key follows `tools` on every body, `false` unless `OllamaOptions.truncate` sets it, and the top-level `shift` key follows that only when its `OllamaOptions` member is set; neither nests in `options`, and `generate` and `stream` encode them identically. An empty `messages` refuses in `encode` with `ProviderError` `'PROTOCOL'` and reaches no transport, because Ollama 0.40.14 answers it with HTTP 200, `done_reason: 'load'`, and no turn. Each tool maps to `{ type: 'function', function: { name } }`, with `description` and `parameters` added only when the corresponding `ToolDefinition` fields are supplied. `title` and `annotations` are **never sent**: the `/api/chat` tool function object carries no field for either. Messages map to the wire's minimal `{ role, content }` turn, with `tool_calls` added only on a turn that replays them and `images` only on a multimodal turn. A non-OK status is the base's failure, not this package's: it throws `ProviderError` with code `'HTTP'`, the response `status`, and a message bounded to an excerpt of the response body. A 400 whose body names the context size, length, or window keeps that code, status, and text and appends `OLLAMA_CONTEXT_REMEDY`.
|
|
224
249
|
4. **Configurable `think` on the wire; the base's splitter keeps the assembled content clean.** For a thinking-capable model (for example `qwen3`) the per-request `think` flag is the only wire-level reasoning control (its native renderer honours neither the qwen3 `/no_think` token nor a Modelfile `PARAMETER think false`). It is configurable through `OllamaOptions.think` (default `false` — so the general-purpose provider stays immediate for non-thinking models and tests fast) and overrideable per call through `ProviderStreamOptions.think`. Set `think: true` when the caller displays reasoning separately from the answer: the daemon then separates reasoning natively, returning it on the distinct `message.thinking` channel, which `read` reports and the engine yields as `ProviderDelta` `{ channel: 'thinking', text }` and accumulates onto `ProviderResult.thinking`. Either way the base's `split` behaviour stays armed, because a daemon may ignore `think: false` for a thinking model and render reasoning inline as `<think>…</think>` content; `OllamaProvider` passes no `split` to `super`, so the default separation applies and the assembled `content` is the splitter's clean accumulation. The agent records the reasoning on the assistant message. `OllamaOptions.replay` filters its return to the provider input, defaulting to `'none'`; the Ollama request mapper omits stored reasoning from the wire.
|
|
225
|
-
5. **One provider NDJSON path.** Every provider call consumes NDJSON — one JSON object per `\n`-terminated line. `frame()` returns `createNDJSONParser({ strict: true })`, fresh per call, so no call inherits another's half-read record, and the base pairs it with a streaming `TextDecoder` so a record split across byte reads is reassembled. A line that is not JSON, or is JSON and not an object, rejects the call as `ProviderError` `'PROTOCOL'` with the parser's `NDJSONError` as its `cause`. The strict parser
|
|
250
|
+
5. **One provider NDJSON path.** Every provider call consumes NDJSON — one JSON object per `\n`-terminated line. `frame()` returns `createNDJSONParser({ strict: true })`, fresh per call, so no call inherits another's half-read record, and the base pairs it with a streaming `TextDecoder` so a record split across byte reads is reassembled. A line that is not JSON, or is JSON and not an object, rejects the call as `ProviderError` `'PROTOCOL'` with the parser's `NDJSONError` as its `cause`. The strict parser passes the daemon's in-band `{"error": ...}` record, because it is an object on its line, so `read` refuses it as `ProviderError` `'PROTOCOL'` with the daemon text bounded like an HTTP excerpt. At end of input the base calls `finish(parser)`, which feeds a trailing `\n` through the parser: a non-conformant proxy's valid final unterminated line is recovered rather than silently dropped, and a malformed one rejects. `read` marks a `done: true` record with `done: true` on the increment, and the engine's strict default rejects a stream whose last increment carries no such mark as `ProviderError` `'PROTOCOL'`: a stream cut on a line boundary leaves nothing malformed, so that mark is what tells it from a whole turn. That option is the engine's and differs from the parser's. A record whose `model` is present and is not the configured tag refuses the same way, and the daemon session owns the digest check.
|
|
226
251
|
6. **`stream` yields deltas and returns the assembled result.** The engine yields each non-empty clean content delta as `{ channel: 'content', text }` and each daemon-side reasoning delta as `{ channel: 'thinking', text }`; its return value is the assembled `ProviderResult` whose `content` is the splitter's authoritative clean accumulation — the concatenation of the yielded content deltas, except across an implicit-open reclassification, where the reasoning prefix had already streamed before a bare `</think>` revealed it and the yields cannot be recalled — plus any tool calls collected across lines, the usage from the `done` line, and the separated `thinking` when the turn produced any.
|
|
227
|
-
7. **Usage and truncation from the `done` line (reuses `TokenUsage`).** `read` reports `usage` only for a record whose `done` is `true` and
|
|
228
|
-
8. **Tool-call extraction with id-generation (no `as`).** `result.tools` is the model's `message.tool_calls`, each entry narrowed to `{ id, name, arguments }`: the entry and its `function` must be records and `name` a string
|
|
229
|
-
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
|
|
252
|
+
7. **Usage and truncation from the `done` line (reuses `TokenUsage`).** `read` reports `usage` only for a record whose `done` is `true` and that carries both `prompt_eval_count` and `eval_count` — mapped to `{ prompt, completion, total: prompt + completion }`, the `TokenUsage` shape, imported rather than redefined. A present count that is not a finite nonnegative number refuses as `ProviderError` `'PROTOCOL'`. Both counts were seen present on every `done` record Ollama 0.40.14 sent, an identical repeat included, and a zero-token answer could not be forced there. A record without both leaves `ProviderResult.usage` absent, and the agent bills its estimate. A delta line carries no counts and a `done: false` line's counts are ignored, so neither contributes usage. `read` projects the same record's `done_reason` through `extractTruncated`: `'length'` (the `num_predict` cap or a full context window) becomes `truncated: true` on the increment and so on `ProviderResult.truncated`, and any other reason, a missing one, or a `done_reason` on a record that is not `done` leaves `truncated` absent. The projection does not read the request's `truncate` setting, so a prompt the daemon cuts under `truncate: true` returns normally and reports nothing. A `done_reason` of `'load'` refuses as `ProviderError` `'PROTOCOL'`, because it reports a model load and no turn.
|
|
253
|
+
8. **Tool-call extraction with id-generation (no `as`).** `result.tools` is the model's `message.tool_calls`, each entry narrowed to `{ id, name, arguments }`: the entry and its `function` must be records and `name` a string, and `arguments` is the wire object as-is or a JSON string parsed to a record. Anything else refuses the turn as `ProviderError` `'PROTOCOL'` naming the entry's position, because a dropped call reads as a final answer and a defaulted argument record reaches a tool as a call it never received. `id` is the wire's `id` when a string, else a freshly minted `crypto.randomUUID()`. An empty result `tools` is never surfaced — its absence means "no calls".
|
|
254
|
+
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.
|
|
230
255
|
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.
|
|
231
256
|
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.
|
|
232
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 is the one emitter in the package, through `OllamaDaemonInterface.emitter`.
|
|
233
258
|
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)).
|
|
234
259
|
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).
|
|
235
|
-
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.
|
|
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.
|
|
236
261
|
|
|
237
|
-
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. 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.
|
|
238
|
-
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`,
|
|
262
|
+
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 or duplicate entries raise a `JudgeError` error with the `PROTOCOL` code. 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.
|
|
239
264
|
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.
|
|
240
|
-
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
|
|
241
|
-
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. 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.
|
|
265
|
+
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
|
+
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.
|
|
242
267
|
21. **Terminal timing.** The `extractTiming` function reads the daemon's own measurements from one parsed record and changes no request, scheduling, usage extraction, or inference count. It returns `undefined` unless the record owns `done: true`. The `OllamaDurations` members map `total_duration`, `load_duration`, `prompt_eval_duration`, and `eval_duration` to `total`, `load`, `prompt`, and `decode`; they are raw integer nanoseconds that the function keeps verbatim and never converts. The `OllamaCounts` members map `prompt_eval_count`, `eval_count`, and `prompt_eval_cached_count` to `prompt`, `decode`, and `cached`; they are tokens. A field the record does not own is unknown: its member is `undefined` and its key is absent from `invalid`, and no member is ever defaulted to zero or inferred. A field the record owns whose value is not a non-negative safe integer, including an own `undefined`, negative zero, a string, a fraction, or an integer above `Number.MAX_SAFE_INTEGER`, also reads `undefined` and its wire key enters `invalid`, in the preceding wire-field order. The function neither mutates the record nor throws for an ordinary unexpected record, and it reads own fields only. Whether a pinned daemon sends each field is a live measurement, not a property of this function.
|
|
243
268
|
|
|
244
269
|
## Daemon session
|
|
245
270
|
|
|
271
|
+
The daemon shape checks string environment values and uses the provider's URL pattern. The runtime guard also requires absolute workspace and store paths, unique model names, and paths without NUL characters. Omit an unused `store`; an explicit `store: undefined` refuses in the guard and the contract. Omit undefined environment entries from the serializable projection; they remain variable removals in the runtime declaration.
|
|
272
|
+
|
|
246
273
|
The server face owns one dedicated Ollama daemon, from a declaration you record before the run, through startup verification and maintenance, to a permanent stop. It runs in Node only, spawns through the process session `@orkestrel/process` publishes, and reports its lifecycle through an `@orkestrel/emitter` emitter. Its declaration refuses the default port 11434, so a session never addresses the daemon other programs share on that port.
|
|
247
274
|
|
|
248
275
|
The optional `fetch` collaborator carries every `/api/version` probe, `/api/tags` verification, and `/api/generate` unload, with the same transport type as the core provider and judge. Supply an instrumented sender to record an attempt before sending it and observe its response headers and stream chunks. The daemon reads the returned body under its existing bounds and retains its maintenance bytes and digests without decoding or reserializing them. Omission uses the global `fetch` bound to `globalThis`.
|
|
@@ -251,7 +278,7 @@ The optional `fetch` collaborator carries every `/api/version` probe, `/api/tags
|
|
|
251
278
|
|
|
252
279
|
A session moves through these steps in order. `PORT` stands for the dedicated port you choose and `NAME` for a declared model name.
|
|
253
280
|
|
|
254
|
-
1. **Declare.** Record the executable's absolute path, its lowercase hexadecimal SHA-256 digest, and the version its `/api/version` route reports, all read before the run. Add the dedicated origin `http://127.0.0.1:PORT` with an explicit port other than 11434 and 0, an absolute working directory, and each model with the digest its `/api/tags` entry reports. `createOllamaDaemon` and the `OllamaDaemon` constructor validate the declaration and copy it before any file, socket, or process operation
|
|
281
|
+
1. **Declare.** Record the executable's absolute path, its lowercase hexadecimal SHA-256 digest, and the version its `/api/version` route reports, all read before the run. Add the dedicated origin `http://127.0.0.1:PORT` with an explicit port other than 11434 and 0, an absolute working directory, and each model with the digest its `/api/tags` entry reports. `createOllamaDaemon` and the `OllamaDaemon` constructor validate the declaration and copy it before any file, socket, or process operation. A malformed declaration throws `OllamaError` with code `invalid`, and an undeclared key in the declaration, `executable`, a `models` entry, `metadata`, or `termination` refuses too, with its path in `context.faults`.
|
|
255
282
|
2. **Start.** `start` checks that the workspace and the optional `store` are existing directories, that the executable is a regular file — a `.exe` or `.com` file on Windows and an executable file elsewhere — and not a `#!` script, and that its bytes hash to the declared digest. It then binds the declared port and releases it, refusing with `occupied` when another process holds the port, and spawns the executable through a process session with the declared `arguments` (default `serve`) and the selected environment. Concurrent and repeated calls share the first startup result.
|
|
256
283
|
3. **Verify.** Readiness wakes on the child's own stderr. `start` requires the child's listen announcement for the declared port, then a `/api/version` reply equal to the declared version, then a `/api/tags` inventory that reports every declared model with its declared digest, and it checks that the owned child is live at each of those replies. Only after every check passes does `start` emit `start` and resolve the frozen `OllamaDaemonIdentity` receipt. `readiness` bounds the whole sequence, `OLLAMA_READINESS` (60000 ms) by default. A failed startup stops and joins the owned session before it rejects, and a cleanup that isn't confirmed rejects with `cleanup` and the startup failure as its `cause`.
|
|
257
284
|
4. **Use.** Point the core face at `daemon.url`, for example `createOllama({ model: NAME, url: daemon.url })`. The session admits no unload before verification and doesn't observe the requests you send.
|
|
@@ -405,7 +432,7 @@ import {
|
|
|
405
432
|
renderJudgePrompt,
|
|
406
433
|
} from '@orkestrel/ollama'
|
|
407
434
|
|
|
408
|
-
const question: JudgeQuestion = { form: 'noul' }
|
|
435
|
+
const question: JudgeQuestion = { form: 'noul', instructions: 'Is it approved?' }
|
|
409
436
|
escapeSpecialTokens('<think>') // '<\u200bthink>'
|
|
410
437
|
const labels = buildJudgeLabels(question)
|
|
411
438
|
labels.get('false') // 'No'
|
|
@@ -494,7 +521,7 @@ request.messages // [{ role: 'user', content: 'Say hello.' }] — ids stay local
|
|
|
494
521
|
const parser = provider.frame()
|
|
495
522
|
parser.parse('{"message":{"content":"Hel"}}\n') // [{ message: { content: 'Hel' } }]
|
|
496
523
|
provider.read({ message: { content: 'lo' }, done: true, prompt_eval_count: 3, eval_count: 4 })
|
|
497
|
-
// { content: 'lo', thinking: '', tools: [], usage: { prompt: 3, completion: 4, total: 7 } }
|
|
524
|
+
// { content: 'lo', thinking: '', tools: [], usage: { prompt: 3, completion: 4, total: 7 }, done: true }
|
|
498
525
|
provider.finish(parser) // [] — the parser held nothing back
|
|
499
526
|
```
|
|
500
527
|
|
|
@@ -633,7 +660,7 @@ try {
|
|
|
633
660
|
if (isProviderError(error) && error.code === 'HTTP' && error.status === 404) {
|
|
634
661
|
// the configured model isn't pulled
|
|
635
662
|
} else if (isProviderError(error) && error.code === 'HTTP' && error.status === 400) {
|
|
636
|
-
// malformed request
|
|
663
|
+
// malformed request, or a prompt over the context window, whose text names the remedy
|
|
637
664
|
} else {
|
|
638
665
|
throw error
|
|
639
666
|
}
|
|
@@ -642,6 +669,36 @@ try {
|
|
|
642
669
|
|
|
643
670
|
A cancel is outside that taxonomy: the caller's signal and the deadline both throw `ProviderAbortError`, which `isProviderAbortError` narrows, and its `partial` carries what had streamed.
|
|
644
671
|
|
|
672
|
+
### A prompt over the context window
|
|
673
|
+
|
|
674
|
+
A provider and a judge send `truncate: false`, so the daemon refuses a prompt over the window instead of cutting it. The following readings come from Ollama 0.40.14 with `qwen3.5:2b` and `num_ctx: 2048` on 2026-11-04.
|
|
675
|
+
|
|
676
|
+
- **`truncate: false`.** `/api/chat` and `/api/generate` each answer HTTP 400 with `request (3245 tokens) exceeds the available context size (2048 tokens), try increasing it`.
|
|
677
|
+
- **`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.
|
|
678
|
+
- **`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.
|
|
679
|
+
|
|
680
|
+
Set `AgentOptions.window` to fold the conversation before the provider call, raise `options.num_ctx`, or set `truncate: true` to let the daemon cut the prompt. Set `window` well under `num_ctx`: real prompt tokens ran 1.23 to 1.78 times `estimateTokens` on the same daemon, and an over-window request refuses.
|
|
681
|
+
|
|
682
|
+
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.
|
|
683
|
+
|
|
684
|
+
A refusal keeps the `HTTP` code and the 400 status, so the following fence narrows it as any other failed call.
|
|
685
|
+
|
|
686
|
+
```ts
|
|
687
|
+
import { isProviderError } from '@orkestrel/agent'
|
|
688
|
+
import { createOllama } from '@orkestrel/ollama'
|
|
689
|
+
|
|
690
|
+
const provider = createOllama({ model: 'qwen3.5:2b', options: { num_ctx: 2048 } })
|
|
691
|
+
const messages = [{ id: '1', role: 'user', content: 'Summarize the attached report.' }] as const
|
|
692
|
+
|
|
693
|
+
try {
|
|
694
|
+
await provider.generate(messages, new AbortController().signal)
|
|
695
|
+
} catch (error) {
|
|
696
|
+
if (isProviderError(error) && error.code === 'HTTP' && error.status === 400) {
|
|
697
|
+
console.log(error.message) // the daemon's text, then the remedy when it names the context
|
|
698
|
+
} else throw error
|
|
699
|
+
}
|
|
700
|
+
```
|
|
701
|
+
|
|
645
702
|
### Run a dedicated daemon
|
|
646
703
|
|
|
647
704
|
The following fence declares a session, starts it, points a provider at it, unloads the declared model, and stops. It starts a real Ollama executable, so this guide's tests never run it: `OLLAMA_PATH`, `OLLAMA_DIGEST`, `MODEL_DIGEST`, and `WORKSPACE` stand for the absolute executable path, its SHA-256 digest, the model's `/api/tags` digest, and an absolute working directory, each recorded before the run.
|
|
@@ -771,9 +828,9 @@ timing?.invalid // []
|
|
|
771
828
|
- **Branch on the code and the status, not the message** — narrow a caught value with `isProviderError` and read `error.code` and `error.status` (`404` for an unpulled model) instead of parsing `error.message`.
|
|
772
829
|
- **Fold usage into a budget** — `result.usage` is the `TokenUsage` shape; `consume` it per turn to enforce a token ceiling.
|
|
773
830
|
- **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`.
|
|
774
|
-
- **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
|
|
831
|
+
- **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.
|
|
775
832
|
- **Tune through `options`** — pass sampling parameters (`temperature`, `seed`, and `num_predict`) through `OllamaOptions.options`; they forward verbatim to the wire.
|
|
776
|
-
- **
|
|
833
|
+
- **Keep the refusal** — leave `OllamaOptions.truncate` at its `false` default so an oversized prompt refuses, and set `AgentOptions.window` or `options.num_ctx` to fit it. Set `truncate: true` only where losing the earlier turns silently is acceptable.
|
|
777
834
|
- **Observe at the call site** — the provider publishes no events; read `stream`'s deltas and its returned result for everything a turn produced.
|
|
778
835
|
|
|
779
836
|
## Tests
|
|
@@ -782,20 +839,20 @@ The judge proofs cover the recorded wire and the live models.
|
|
|
782
839
|
|
|
783
840
|
- [`tests/src/core/OllamaJudge.test.ts`](../tests/src/core/OllamaJudge.test.ts) drives the raw wire over recorded bodies, including refusals, limits before inference, usage, and cancellation.
|
|
784
841
|
- [`tests/src/core/helpers.test.ts`](../tests/src/core/helpers.test.ts) compares the rendered prompts byte for byte and checks calibration, candidate-only normalization, label mapping, escaping, and identity.
|
|
785
|
-
- [`tests/service/judge.test.ts`](../tests/service/judge.test.ts) requires Mica and the native decision model, reads the deletion noul within 0.005 of the desk's pinned No probability 0.9884, asks the native model every form in one request,
|
|
842
|
+
- [`tests/service/judge.test.ts`](../tests/service/judge.test.ts) requires Mica and the native decision model, reads the deletion noul within 0.005 of the desk's pinned No probability 0.9884, asks the native model every form in one request, asserts Mica's System One HTTP 400 refusal, and reads the HTTP 400 and its remedy on a Mica prompt over the context window beside the answer `truncate: true` gives for the same prompt. `OLLAMA_JUDGE_MODEL`, `OLLAMA_JUDGE_TEMPERATURE`, and `OLLAMA_DECISION_MODEL` override the recorded defaults. Mica warmup admits 300000 ms because the recorded cold load took 230850 ms.
|
|
786
843
|
|
|
787
|
-
The daemon session proofs run in the `src:server` project against `tests/src/server/fixtures/daemon.mjs`, a self-contained fake daemon that the running Node executable starts on a loopback port, and in the `service` project against a real Ollama executable.
|
|
844
|
+
The daemon session proofs run in the `src:server` project against `tests/src/server/fixtures/daemon.mjs`, a self-contained fake daemon that the running Node executable starts on a loopback port and that answers each route with the fields a real daemon sends, and in the `service` project against a real Ollama executable.
|
|
788
845
|
|
|
789
846
|
- [`tests/src/server/OllamaDaemon.test.ts`](../tests/src/server/OllamaDaemon.test.ts) drives the lifecycle over the fake daemon: a shared startup behind a delayed version reply, verification before any model request, retained maintenance including a refused unload, an overlapping unload, and a refused restart; ordered requests through an optional transport and its global control, exact maintenance bytes across re-chunked replies, a retained transport reference after caller mutation, and transport refusals at each send boundary, with startup joining the child before rejecting and unload leaving it running until `stop`; a mismatched inventory digest refused with `model`, metadata-only requests, and the owned child joined before startup rejects; a stale executable digest and an occupied port, each refused before a child exists; silence, an exit before listening, a bind failure, and an exit before answering, each refused with the owned child gone; executable bytes replaced through the declared path during use, which `stop` reports as `false` with a `digest` error; and a stop and an abort that each end the daemon and its runner while an unrelated process survives.
|
|
790
847
|
- [`tests/src/server/helpers.test.ts`](../tests/src/server/helpers.test.ts) proves the environment merge by case-folded name, the listen announcement match, the version and model comparisons, the bounded metadata exchange and its refusals, the retained bytes and their digests, the exact unload body, and the terminal reply check, over an in-process peer that answers the metadata routes.
|
|
791
|
-
- [`tests/src/server/validators.test.ts`](../tests/src/server/validators.test.ts), [`tests/src/server/factories.test.ts`](../tests/src/server/factories.test.ts), and [`tests/src/server/errors.test.ts`](../tests/src/server/errors.test.ts) prove the declaration refusals before any spawn, an unstarted session's release without a spawn, and the error brand, its context copy, its cause, and the guard's refusals.
|
|
848
|
+
- [`tests/src/server/validators.test.ts`](../tests/src/server/validators.test.ts), [`tests/src/server/factories.test.ts`](../tests/src/server/factories.test.ts), and [`tests/src/server/errors.test.ts`](../tests/src/server/errors.test.ts) prove the declaration refusals before any spawn, the undeclared keys by path, the guards in lockstep with the shape, an unstarted session's release without a spawn, and the error brand, its context copy, its cause, and the guard's refusals.
|
|
792
849
|
- [`tests/service/OllamaDaemon.test.ts`](../tests/service/OllamaDaemon.test.ts) starts a dedicated real daemon, verifies its receipt, unloads every declared model with the exact request body, and requires a confirmed stop without generation. An explicit `OLLAMA_DAEMON_DECLARATION` JSON value wins. Otherwise the proof resolves `OLLAMA_DAEMON_EXECUTABLE` or the `ollama` executable on `PATH` to its canonical path, computes its SHA-256, reads the provisioned service at `OLLAMA_HOST` for its version and the selected model's `/api/tags` digest, and chooses an ephemeral loopback port apart from 11434 and the provisioned service port. It runs only in the `service` project.
|
|
793
850
|
|
|
794
851
|
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.
|
|
795
852
|
|
|
796
853
|
- [`tests/guides.test.ts`](../tests/guides.test.ts) — the `## Surface` ↔ `src/core` and `src/server` bijection (value + type exports), the `OllamaProvider`, `OllamaJudge`, and `OllamaDaemonInterface` 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.
|
|
797
|
-
- [`tests/src/core/OllamaProvider.test.ts`](../tests/src/core/OllamaProvider.test.ts) — hermetic provider request-shape (including the
|
|
798
|
-
- [`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
|
|
854
|
+
- [`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.
|
|
855
|
+
- [`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.
|
|
799
856
|
- [`tests/src/core/factories.test.ts`](../tests/src/core/factories.test.ts) — hermetic `createOllama` shape, identity, defaults, passthrough, and unreachable-upstream coverage.
|
|
800
857
|
- [`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, recap, 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).
|
|
801
858
|
- [`tests/setup.test.ts`](../tests/setup.test.ts) — the shared host-independent test infrastructure, over the conversation padding, the window consumers, the throwing and recording summarizers, 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.
|
|
@@ -812,13 +869,13 @@ The hermetic projects — `src:core`, `src:server`, `setup`, `guides`, `conforma
|
|
|
812
869
|
- [`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.
|
|
813
870
|
- [`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.
|
|
814
871
|
- [`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.
|
|
815
|
-
- [`tests/service/compaction.test.ts`](../tests/service/compaction.test.ts) and [`tests/service/conversation.test.ts`](../tests/service/conversation.test.ts) — live recap retention with manual, automatic, and repeated compaction, and
|
|
872
|
+
- [`tests/service/compaction.test.ts`](../tests/service/compaction.test.ts) and [`tests/service/conversation.test.ts`](../tests/service/conversation.test.ts) — live recap retention with manual, automatic, and repeated compaction, and a throwing summarizer that rejects the run under the strict default and stays non-fatal under `strict: false`, and long-conversation instruction behavior, with proxy calls explicitly forwarding to `OLLAMA_CONFIG.host`.
|
|
816
873
|
|
|
817
874
|
## See also
|
|
818
875
|
|
|
819
876
|
- `@orkestrel/agent` — the `AgentProvider` engine this package extends, the `ProviderInterface` contract, the errors, and the relay. Its guide is mirrored here as [`agent.md`](agent.md) and ships with that package.
|
|
820
877
|
- `@orkestrel/ndjson` — the parser `frame()` returns for each call. Its guide ships with that package.
|
|
821
|
-
- `@orkestrel/contract` — the `isRecord` / `isString` / `
|
|
878
|
+
- `@orkestrel/contract` — the `isRecord` / `isString` / `parseJSONAs` helpers that narrow the wire `unknown`, and the shapes the constructors check their options against. Its guide ships with that package.
|
|
822
879
|
- `@orkestrel/process` and `@orkestrel/emitter` — the process session the daemon session spawns through and the emitter that carries its lifecycle events. Each guide ships with its own package.
|
|
823
880
|
- `@orkestrel/router` and `@orkestrel/server` — the dispatcher the relay handler mounts on and the listener that serves it, mirrored here as [`router.md`](router.md) and [`server.md`](server.md). Each ships with its own package.
|
|
824
881
|
- [`AGENTS.md`](../AGENTS.md) — the coding rules this package is written to.
|