@orkestrel/scaffold 0.0.133 → 0.0.135
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-dispatch/scripts/bench.js +61 -96
- package/dist/agents/skills/orkestrel-dispatch/scripts/brief.js +48 -76
- package/dist/agents/skills/orkestrel-dispatch/scripts/chain.js +27 -66
- package/dist/agents/skills/orkestrel-dispatch/scripts/cite.js +31 -64
- package/dist/agents/skills/orkestrel-dispatch/scripts/launch.js +43 -57
- package/dist/agents/skills/orkestrel-dispatch/scripts/login.js +43 -86
- package/dist/agents/skills/orkestrel-dispatch/scripts/patch.js +68 -104
- package/dist/agents/skills/orkestrel-dispatch/scripts/result.js +35 -69
- package/dist/agents/skills/orkestrel-dispatch/scripts/sweep.js +47 -84
- package/dist/agents/skills/orkestrel-falsify/scripts/mutate.js +134 -116
- package/dist/agents/skills/orkestrel-harden/scripts/discovery.js +38 -90
- package/dist/agents/skills/orkestrel-harden/scripts/interleave.js +39 -103
- package/dist/agents/skills/orkestrel-harden/scripts/measure.js +40 -89
- package/dist/agents/skills/orkestrel-harden/scripts/titles.js +41 -87
- package/dist/agents/skills/orkestrel-parallel/scripts/cases.js +43 -88
- package/dist/agents/skills/orkestrel-parallel/scripts/lane.js +1568 -213
- package/dist/agents/skills/orkestrel-publish/scripts/compare.js +40 -60
- package/dist/agents/skills/orkestrel-publish/scripts/pins.js +47 -81
- package/dist/agents/skills/orkestrel-publish/scripts/steps.js +66 -104
- package/dist/agents/skills/orkestrel-publish/scripts/swap.js +74 -88
- package/dist/agents/skills/orkestrel-publish/scripts/wave.js +387 -109
- package/dist/agents/skills/orkestrel-publish/scripts/window.js +55 -96
- package/dist/agents/skills/orkestrel-scout/scripts/map.js +54 -101
- package/dist/bin/main.js +275 -33
- package/dist/bin/main.js.map +1 -1
- package/dist/host/AGENTS.md +1 -1
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/bench.ts +81 -97
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/brief.ts +64 -72
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/chain.ts +41 -63
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/cite.ts +56 -79
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/launch.ts +61 -74
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/login.ts +59 -89
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/patch.ts +87 -106
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/result.ts +57 -76
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/sweep.ts +73 -88
- package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +2 -2
- package/dist/host/agents/skills/orkestrel-falsify/scripts/mutate.ts +167 -119
- package/dist/host/agents/skills/orkestrel-harden/references/methods.md +1 -1
- package/dist/host/agents/skills/orkestrel-harden/scripts/discovery.ts +58 -75
- package/dist/host/agents/skills/orkestrel-harden/scripts/interleave.ts +55 -99
- package/dist/host/agents/skills/orkestrel-harden/scripts/measure.ts +59 -90
- package/dist/host/agents/skills/orkestrel-harden/scripts/titles.ts +60 -80
- package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +4 -4
- package/dist/host/agents/skills/orkestrel-parallel/scripts/cases.ts +71 -108
- package/dist/host/agents/skills/orkestrel-parallel/scripts/lane.ts +1990 -274
- package/dist/host/agents/skills/orkestrel-publish/references/release.md +1 -0
- package/dist/host/agents/skills/orkestrel-publish/references/wave.md +28 -7
- package/dist/host/agents/skills/orkestrel-publish/scripts/compare.ts +58 -79
- package/dist/host/agents/skills/orkestrel-publish/scripts/pins.ts +66 -87
- package/dist/host/agents/skills/orkestrel-publish/scripts/steps.ts +84 -102
- package/dist/host/agents/skills/orkestrel-publish/scripts/swap.ts +92 -99
- package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +483 -127
- package/dist/host/agents/skills/orkestrel-publish/scripts/window.ts +82 -120
- package/dist/host/agents/skills/orkestrel-scout/SKILL.md +3 -3
- package/dist/host/agents/skills/orkestrel-scout/scripts/map.ts +85 -112
- package/dist/host/claude/agents/orkestrel.md +16 -16
- package/dist/host/claude/rules/architecture.md +1 -1
- package/dist/host/claude/rules/documentation.md +1 -1
- package/dist/host/claude/rules/patterns.md +7 -4
- package/dist/host/claude/rules/styles.md +1 -1
- package/dist/host/claude/rules/tests.md +3 -3
- package/dist/host/claude/rules/workspace.md +50 -37
- package/dist/host/configs/helpers.ts +117 -71
- package/dist/host/dotfiles/oxlintrc.json +6 -0
- package/dist/host/guides/agent.md +989 -395
- package/dist/host/guides/database.md +357 -342
- package/dist/host/guides/form.md +79 -4
- package/dist/host/guides/middleware.md +5 -5
- package/dist/host/guides/ollama.md +41 -42
- package/dist/host/guides/scaffold.md +170 -70
- package/dist/host/guides/study.md +12 -12
- package/dist/host/guides/table.md +20 -6
- package/dist/host/guides/test.md +166 -52
- package/dist/host/guides/toolbox.md +127 -81
- package/dist/host/guides/workspace.md +21 -14
- package/dist/host/manifest.json +54 -54
- package/dist/host/tests/config.test.ts +251 -7
- package/dist/host/tests/policy.test.ts +14 -21
- package/dist/host/tests/setupPolicy.ts +43 -36
- package/dist/src/core/index.cjs +533 -139
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +223 -16
- package/dist/src/core/index.d.ts +223 -16
- package/dist/src/core/index.js +524 -139
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +23 -14
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +3 -2
- package/dist/src/server/index.d.ts +3 -2
- package/dist/src/server/index.js +24 -15
- package/dist/src/server/index.js.map +1 -1
- package/package.json +2 -2
package/dist/host/guides/form.md
CHANGED
|
@@ -229,7 +229,7 @@ The browser entry publishes the controlled native form and its host readers.
|
|
|
229
229
|
| `FormControl` | type | `HTMLInputElement \| HTMLSelectElement \| HTMLTextAreaElement` | Represents a native answer control admitted by the binding. |
|
|
230
230
|
| `FormBindingErrorCode` | type | `'CONTROL' \| 'PENDING' \| 'DOM'` | Names a native binding refusal. |
|
|
231
231
|
| `FormBindingEventMap` | type | `{ readonly render: readonly []; readonly write: readonly [control: FormControl]; readonly submit: readonly [submission: FormSubmission, submitter: HTMLElement \| undefined]; readonly error: readonly [error: unknown]; }` | Lists the native binding's notifications after their associated DOM effects. |
|
|
232
|
-
| `FormBindingOptions` | interface | `{ feedback?, summary?, presentations?, defer?, on?, error? }`
|
|
232
|
+
| `FormBindingOptions` | interface | `{ feedback?, summary?, presentations?, defer?, reveal?, on?, error? }` | Configures neutral feedback destinations and isolated event listeners. |
|
|
233
233
|
| `FormBindingInterface` | interface | `{ element, document, destroyed, emitter, read(), refresh(), destroy() }` | Declares a native form's borrowed document and synchronization lifecycle. |
|
|
234
234
|
| `FormBindingAttribute` | interface | `{ original, value }` | Records an attribute's authored value and the binding's last contribution. |
|
|
235
235
|
| `FormBindingValidity` | interface | `{ original, value }` | Records the binding's custom-validity contribution beside the authored message. |
|
|
@@ -239,6 +239,7 @@ The browser entry publishes the controlled native form and its host readers.
|
|
|
239
239
|
| `isFormBindingError` | function | `(value: unknown) => value is FormBindingError` | Checks whether a value is a native binding refusal. |
|
|
240
240
|
| `isFormControl` | function | `(value: unknown) => value is FormControl` | Checks whether a value is a native answer control. |
|
|
241
241
|
| `matchesFormControls` | function | `(field: FormField, controls: readonly FormControl[]) => boolean` | Checks a native control population against a field's declared value shape. |
|
|
242
|
+
| `matchesNativeNumber` | function | `(control: FormControl, value: FieldValue \| undefined) => boolean` | Checks whether a numeric control's own text already parses to the document's number. |
|
|
242
243
|
| `readNativeMessages` | function | `(control: FormControl, errors: readonly FieldError[]) => readonly string[]` | Reads native constraint messages not already reported by document rules. |
|
|
243
244
|
| `readFormControls` | function | `(field: FormField, controls: readonly FormControl[]) => FieldValue \| undefined` | Reads one compatible native population using the document's blank-to-absence semantics. |
|
|
244
245
|
|
|
@@ -261,6 +262,18 @@ readFormControls({ control: 'text', name: 'name' }, [input]) // 'Ada'
|
|
|
261
262
|
isFormBindingError(new FormBindingError('CONTROL', 'Duplicate controls')) // true
|
|
262
263
|
```
|
|
263
264
|
|
|
265
|
+
The projection keeps a number input's own text while it parses to the document's number.
|
|
266
|
+
|
|
267
|
+
```ts
|
|
268
|
+
import { matchesNativeNumber } from '@orkestrel/form/browser'
|
|
269
|
+
|
|
270
|
+
const price = document.createElement('input')
|
|
271
|
+
price.type = 'number'
|
|
272
|
+
price.value = '1.50'
|
|
273
|
+
matchesNativeNumber(price, 1.5) // true — the binding leaves '1.50' in place
|
|
274
|
+
matchesNativeNumber(price, 1.25) // false — the binding writes '1.25'
|
|
275
|
+
```
|
|
276
|
+
|
|
264
277
|
## Controls
|
|
265
278
|
|
|
266
279
|
Each control fixes both the options its field accepts and the `FieldValue` it holds. The `confirm`,
|
|
@@ -1254,6 +1267,18 @@ the failure lasts until that field is filled again or the form is cleared.
|
|
|
1254
1267
|
captured enabled fields to their submitted values or absence. It is what `dirty` measures against
|
|
1255
1268
|
and what `clear` returns to. Read `extractChanges(form.values, form.baseline)` for the changed names.
|
|
1256
1269
|
|
|
1270
|
+
An empty list and absence are equal in change extraction, in either direction. A list field that
|
|
1271
|
+
opens with no baseline answer and is read back empty therefore stays clean, so `dirty` stays false
|
|
1272
|
+
until an entry arrives. Every other answer, the empty string included, differs from absence.
|
|
1273
|
+
|
|
1274
|
+
```ts
|
|
1275
|
+
import { extractChanges } from '@orkestrel/form'
|
|
1276
|
+
|
|
1277
|
+
Array.from(extractChanges({ to: [] }, {})) // [] — an empty list matches an absent baseline
|
|
1278
|
+
Array.from(extractChanges({ to: ['ada@example.com'] }, {})) // ['to']
|
|
1279
|
+
Array.from(extractChanges({ subject: '' }, {})) // ['subject']
|
|
1280
|
+
```
|
|
1281
|
+
|
|
1257
1282
|
`clear` returns every answer to `baseline`. It also clears `touched`, every external failure, and
|
|
1258
1283
|
every runtime `disable` or `enable`. Pending acknowledgement is aborted; the disabled state returns
|
|
1259
1284
|
to the schema's declarations and the answers return to the acknowledged baseline.
|
|
@@ -1584,6 +1609,27 @@ without reachable controls remain text. An invalid submission focuses the first
|
|
|
1584
1609
|
control. The binding never invokes a native validity popup. A `render` event follows DOM effects,
|
|
1585
1610
|
including effects triggered by core changes, so a presentation adapter can apply its own classes.
|
|
1586
1611
|
|
|
1612
|
+
### Reveal a refused field
|
|
1613
|
+
|
|
1614
|
+
An invalid submission focuses only a control a person can reach. A field whose control sits on
|
|
1615
|
+
another page, behind a search, or in a hidden pane has none. Supply `reveal` to bring that field
|
|
1616
|
+
into the document. A refused field a person can already reach takes focus first, and the hook does
|
|
1617
|
+
not run. When none is reachable, the binding calls the hook with each refused field's name in order,
|
|
1618
|
+
rediscovers controls after each call, and focuses the first field the hook made reachable. The hook
|
|
1619
|
+
returns nothing and the binding awaits nothing; a host whose reveal finishes later focuses the
|
|
1620
|
+
field itself. A throw reaches the binding's `error` event and focuses nothing.
|
|
1621
|
+
|
|
1622
|
+
```ts
|
|
1623
|
+
import { createFormBinding } from '@orkestrel/form/browser'
|
|
1624
|
+
|
|
1625
|
+
const binding = createFormBinding(element, model, {
|
|
1626
|
+
reveal: (name) => {
|
|
1627
|
+
search.clear()
|
|
1628
|
+
pager.show(name)
|
|
1629
|
+
},
|
|
1630
|
+
})
|
|
1631
|
+
```
|
|
1632
|
+
|
|
1587
1633
|
Native and document validation remain distinct sources. A named rule's message replaces feedback
|
|
1588
1634
|
for that native constraint. Required, bounds, length, step, pattern, email, and URL failures match
|
|
1589
1635
|
by rule identity, never localized text. A lone uncovered failure keeps the platform's message.
|
|
@@ -1668,9 +1714,16 @@ workaround and the scalar comma-splitting validator for recipient arrays.
|
|
|
1668
1714
|
|
|
1669
1715
|
Set `defer: true` to hold blur-triggered touch while a primary pointer press on an enabled button
|
|
1670
1716
|
associated with this form is active. This includes externally associated buttons and presses on
|
|
1671
|
-
their descendants. Touch resumes in a task after
|
|
1672
|
-
sequence free of blur feedback that moves the
|
|
1673
|
-
|
|
1717
|
+
their descendants. Touch resumes in a task after the press's click, after cancellation, or after a
|
|
1718
|
+
release away from the button, leaving the click sequence free of blur feedback that moves the
|
|
1719
|
+
button. Keyboard blur remains immediate; input reads and submission validation remain immediate.
|
|
1720
|
+
Reset and destruction discard deferred touch.
|
|
1721
|
+
|
|
1722
|
+
A release on the button whose click never reaches the binding keeps the touch pending: a click a
|
|
1723
|
+
listener prevented, or one a listener stopped. The touch then waits for a reset, which discards it, or for the next focus change, which applies it.
|
|
1724
|
+
A later press on a form button carries the pending touch and decides it by its own click. A
|
|
1725
|
+
confirmation gate that holds its first press back therefore keeps the field's feedback still while
|
|
1726
|
+
it is armed, and the confirming press resets the form with nothing shown.
|
|
1674
1727
|
|
|
1675
1728
|
Enable deferral where feedback can move an action under the pointer.
|
|
1676
1729
|
|
|
@@ -1680,6 +1733,25 @@ import { createFormBinding } from '@orkestrel/form/browser'
|
|
|
1680
1733
|
const binding = createFormBinding(element, model, { defer: true })
|
|
1681
1734
|
```
|
|
1682
1735
|
|
|
1736
|
+
For a reset button behind a confirmation gate, let the gate hold the arming click back. The field
|
|
1737
|
+
stays untouched until the confirming click resets the form or focus moves on.
|
|
1738
|
+
|
|
1739
|
+
```ts
|
|
1740
|
+
import { createFormBinding } from '@orkestrel/form/browser'
|
|
1741
|
+
|
|
1742
|
+
const binding = createFormBinding(element, model, { defer: true })
|
|
1743
|
+
window.addEventListener(
|
|
1744
|
+
'click',
|
|
1745
|
+
(event) => {
|
|
1746
|
+
if (!event.composedPath().includes(discard) || gate.armed) return
|
|
1747
|
+
event.preventDefault()
|
|
1748
|
+
event.stopImmediatePropagation()
|
|
1749
|
+
gate.arm()
|
|
1750
|
+
},
|
|
1751
|
+
{ capture: true },
|
|
1752
|
+
)
|
|
1753
|
+
```
|
|
1754
|
+
|
|
1683
1755
|
### Native capability boundaries
|
|
1684
1756
|
|
|
1685
1757
|
The browser admits text, search, email, URL, telephone, hidden, password, textarea, number, range,
|
|
@@ -1687,6 +1759,9 @@ date, time, datetime-local, color, confirm, radio, single select, multiple selec
|
|
|
1687
1759
|
and file inputs. Blank strings become absence through the core's answer predicate; false, zero, and
|
|
1688
1760
|
empty lists remain answers. A password field accepts both `password` and `text` inputs, so a reveal
|
|
1689
1761
|
toggle retains discovery, validation, and summary links without mirroring the value.
|
|
1762
|
+
A number or range input whose own text parses to the document's number keeps that text, so a typed
|
|
1763
|
+
`1.50` survives every projection of `1.5`, and a different number rewrites it. The comparison reads
|
|
1764
|
+
the input's own locale-independent value with the document's equality, and blank text never matches.
|
|
1690
1765
|
Numeric bad input remains a native error and never becomes NaN or a
|
|
1691
1766
|
valid absent answer. Explicit refresh discards that unreadable native text and repaints the document's
|
|
1692
1767
|
answer; ordinary input, touch, and submit keep the text available for correction. Native constraints
|
|
@@ -755,10 +755,10 @@ The `session` column holds the `SessionSnapshot` JSON that `snapshotSession`
|
|
|
755
755
|
writes and `createRestoredSession` reads back: `{ id, state }`, where `state`
|
|
756
756
|
carries the session's entries. The cursor columns are `seen` and `created`. A
|
|
757
757
|
table still declared with the earlier `lastSeen` and `createdAt` columns fails
|
|
758
|
-
closed rather than reading a stale row as live: the table
|
|
759
|
-
|
|
760
|
-
`
|
|
761
|
-
recreated.
|
|
758
|
+
closed rather than reading a stale row as live: the table raises a `DRIVER`
|
|
759
|
+
`DatabaseError` for a row that does not satisfy `sessionColumns`, `store.get`
|
|
760
|
+
and `store.set` reject with it, and the row stays in place until the table is
|
|
761
|
+
migrated or recreated.
|
|
762
762
|
|
|
763
763
|
### Session transport seam — direct calls
|
|
764
764
|
|
|
@@ -1064,7 +1064,7 @@ console.log(extractFieldToken({ csrf: 'credential' }, 'csrf'))
|
|
|
1064
1064
|
absolute-lifetime eviction (including the underlying row's removal),
|
|
1065
1065
|
`created` stamped once and preserved across re-set, guard rejection,
|
|
1066
1066
|
construction guards, rebuild through the injected restore step, and the
|
|
1067
|
-
|
|
1067
|
+
propagated `DRIVER` refusal of a row stored under the earlier cursor columns.
|
|
1068
1068
|
- [`tests/src/core/factories.test.ts`](../tests/src/core/factories.test.ts) —
|
|
1069
1069
|
`createCookieTransport`/`createHeaderTransport` round-trips over real
|
|
1070
1070
|
`Request`/`Response`, `createMemorySessionStore` shallow mirror,
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
> The Ollama chat provider wire on the `/api/chat` path and the raw judge wire for Mica
|
|
4
4
|
> on the `/api/generate` path, with shared engines from the `@orkestrel/agent` package.
|
|
5
5
|
|
|
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,
|
|
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, records the version the daemon reports, verifies every declared model digest, unloads the declared models, and stops the process tree it started; see [Daemon session](#daemon-session).
|
|
7
7
|
|
|
8
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
|
|
|
@@ -149,39 +149,39 @@ The raw judge exports the following declarations.
|
|
|
149
149
|
|
|
150
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.
|
|
151
151
|
|
|
152
|
-
| Name | Kind | Signature
|
|
153
|
-
| ------------------------- | --------- |
|
|
154
|
-
| `createOllamaDaemon` | function | `(options: OllamaDaemonOptions) => OllamaDaemonInterface`
|
|
155
|
-
| `OllamaDaemon` | class | `new (options: OllamaDaemonOptions) => OllamaDaemonInterface`
|
|
156
|
-
| `OllamaDaemonInterface` | interface | `{ url, identity, maintenance, emitter, start(), unload(), stop(), destroy() }`
|
|
157
|
-
| `OllamaDaemonOptions` | interface | `{ on?, error?, executable, url, models, workspace, environment?, store?, readiness?, metadata?, termination?, signal? }`
|
|
158
|
-
| `OllamaExecutable` | interface | `{ path, digest,
|
|
159
|
-
| `OllamaModel` | interface | `{ name, digest }`
|
|
160
|
-
| `OllamaMetadataOptions` | interface | `{ timeout?, bytes? }`
|
|
161
|
-
| `OllamaDaemonIdentity` | interface | `{ executable, url, pid, models }`
|
|
162
|
-
| `OllamaBytes` | interface | `{ content, size, digest, complete }`
|
|
163
|
-
| `OllamaMaintenance` | interface | `{ sequence, model, url, request, response?, status?, timing?, error? }`
|
|
164
|
-
| `OllamaDaemonEventMap` | type | `{ readonly start: readonly [identity: OllamaDaemonIdentity]; readonly unload: readonly [maintenance: OllamaMaintenance]; readonly stop: readonly [confirmed: boolean]; readonly error: readonly [error: unknown]; }`
|
|
165
|
-
| `ollamaDaemonShape` | const | `import("@orkestrel/contract").ObjectShape<{ executable: import("@orkestrel/contract").ObjectShape<{ path: import("@orkestrel/contract").StringShape; digest: import("@orkestrel/contract").StringShape;
|
|
166
|
-
| `ollamaDaemonContract` | const | `ContractInterface<unknown>`
|
|
167
|
-
| `OLLAMA_TIMER_LIMIT` | const | `2147483647`
|
|
168
|
-
| `OLLAMA_DAEMON_LIVE` | const | `readonly string[]`
|
|
169
|
-
| `OLLAMA_DAEMON_KEYS` | const | `Readonly<{ daemon: readonly string[]; executable: readonly string[]; model: readonly string[]; metadata: readonly string[]; termination: readonly string[]; }>`
|
|
170
|
-
| `OLLAMA_READINESS` | const | `60000`
|
|
171
|
-
| `OLLAMA_METADATA_TIMEOUT` | const | `10000`
|
|
172
|
-
| `OLLAMA_METADATA_BYTES` | const | `1048576`
|
|
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, 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, version, 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; 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 the version probe 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. |
|
|
173
173
|
|
|
174
174
|
The server face reports every refusal as one branded error class.
|
|
175
175
|
|
|
176
|
-
| Name | Kind | Signature
|
|
177
|
-
| -------------------- | --------- |
|
|
178
|
-
| `OllamaError` | class | `new (message: string, options: OllamaErrorOptions) => OllamaError`
|
|
179
|
-
| `OllamaErrorOptions` | interface | `{ code, context?, cause? }`
|
|
180
|
-
| `OllamaErrorContext` | interface | `{ operation?, path?, url?, model?, expected?, received?, evidence?, faults? }`
|
|
181
|
-
| `OllamaErrorCode` | type | `(typeof OLLAMA_ERROR_CODES)[number]`
|
|
182
|
-
| `OLLAMA_ERROR_CODES` | const | `readonly ["invalid", "occupied", "digest", "spawn", "readiness", "
|
|
183
|
-
| `OLLAMA_ERROR_BRAND` | const | `unique symbol`
|
|
184
|
-
| `isOllamaError` | function | `(value: unknown) => value is OllamaError`
|
|
176
|
+
| Name | Kind | Signature | Summary |
|
|
177
|
+
| -------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
|
|
178
|
+
| `OllamaError` | class | `new (message: string, options: OllamaErrorOptions) => OllamaError` | Carries a daemon refusal with a machine-readable category, observations, and original cause. |
|
|
179
|
+
| `OllamaErrorOptions` | interface | `{ code, context?, cause? }` | Configures a daemon refusal with its category, observations, and original cause. |
|
|
180
|
+
| `OllamaErrorContext` | interface | `{ operation?, path?, url?, model?, expected?, received?, evidence?, faults? }` | Carries the operation and identity observations accompanying a daemon refusal. |
|
|
181
|
+
| `OllamaErrorCode` | type | `(typeof OLLAMA_ERROR_CODES)[number]` | Defines the machine-readable refusal categories of the daemon lifecycle. |
|
|
182
|
+
| `OLLAMA_ERROR_CODES` | const | `readonly ["invalid", "occupied", "digest", "spawn", "readiness", "model", "owner", "metadata", "unload", "cleanup", "aborted", "state"]` | Lists every machine-readable daemon refusal category. |
|
|
183
|
+
| `OLLAMA_ERROR_BRAND` | const | `unique symbol` | Identifies daemon errors across installations and module formats through the global symbol registry. |
|
|
184
|
+
| `isOllamaError` | function | `(value: unknown) => value is OllamaError` | Checks whether an unknown value carries the daemon error brand and declared members. |
|
|
185
185
|
|
|
186
186
|
The session composes the following validators and protocol helpers, each exported so a caller can check a declaration or a retained body without starting a daemon.
|
|
187
187
|
|
|
@@ -194,7 +194,7 @@ The session composes the following validators and protocol helpers, each exporte
|
|
|
194
194
|
| `isOllamaOrigin` | function | `(value: unknown) => value is string` | Checks whether a string selects an explicit dedicated HTTP loopback origin. |
|
|
195
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. |
|
|
196
196
|
| `matchesOllamaAnnouncement` | function | `(line: string, url: string) => boolean` | Checks whether stderr announces the dedicated loopback listener. |
|
|
197
|
-
| `
|
|
197
|
+
| `readOllamaVersion` | function | `(value: unknown) => string` | Reads the version a metadata reply reports, whatever it is. |
|
|
198
198
|
| `verifyOllamaModels` | function | `(value: unknown, models: readonly OllamaModel[]) => void` | Verifies every declared model against a complete metadata inventory. |
|
|
199
199
|
| `retainOllamaBytes` | function | `(bytes: Uint8Array, complete: boolean) => OllamaBytes` | Retains exact body bytes with an independently reproducible digest. |
|
|
200
200
|
| `readOllamaJSON` | function | `(bytes: OllamaBytes) => Readonly<Record<string, unknown>>` | Reads a complete retained JSON metadata body without reserializing it. |
|
|
@@ -278,9 +278,9 @@ The optional `fetch` collaborator carries every `/api/version` probe, `/api/tags
|
|
|
278
278
|
|
|
279
279
|
A session moves through these steps in order. `PORT` stands for the dedicated port you choose and `NAME` for a declared model name.
|
|
280
280
|
|
|
281
|
-
1. **Declare.** Record the executable's absolute path
|
|
281
|
+
1. **Declare.** Record the executable's absolute path and its lowercase hexadecimal SHA-256 digest, both read before the run. The declaration names no version, so an Ollama update never invalidates it. 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`.
|
|
282
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.
|
|
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
|
|
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 that names a nonempty 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. The reported version is an observation: `start` compares it with nothing and records it as the receipt's `version`, and a reply that names no version refuses with `metadata`. 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`.
|
|
284
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.
|
|
285
285
|
5. **Unload.** `unload` posts `{"model":NAME,"keep_alive":0}` to `/api/generate` for each declared model in declaration order, with no prompt, and retains each request and response as `OllamaBytes`: the base64 content, its byte count, its SHA-256 digest, and whether the body ended within its bound. An attempt succeeds only when the complete terminal reply carries `done: true` and names the declared model. The first refused attempt ends the call, and every attempt, refused ones included, stays in `maintenance` in sequence order. A transport or collaborator failure, or a refused reply, rejects `unload` and leaves the daemon running until `stop`; a rejection during `start` stops and joins the child before rejecting. A call that overlaps another refuses with `state`.
|
|
286
286
|
6. **Stop.** `stop` is permanent. It aborts pending startup and maintenance, stops the owned process tree, joins the session's exit barrier, and hashes the executable again. It resolves `true` when the root exit is confirmed and the digest is unchanged, or when no child ever started; otherwise it emits `error` and resolves `false`. It never rejects, every call shares one barrier, and a stopped session refuses to start with `state`. `destroy` stops the session and then releases its emitter; `identity` and `maintenance` stay readable after it.
|
|
@@ -325,10 +325,9 @@ Declare each model's digest as the `digest` field its `/api/tags` entry reports,
|
|
|
325
325
|
| `digest` | an executable whose digest differs or can't be read, before spawn or after stop |
|
|
326
326
|
| `spawn` | another preflight or spawn failure, such as a missing executable or a child that couldn't be created |
|
|
327
327
|
| `readiness` | the startup deadline, which a child that never announces its listener reaches |
|
|
328
|
-
| `version` | a `/api/version` reply that differs from the declared version |
|
|
329
328
|
| `model` | a declared model the inventory omits or reports with another digest |
|
|
330
329
|
| `owner` | an owned child that isn't live at a readiness reply or at maintenance |
|
|
331
|
-
| `metadata` | a refused status, a redirect, a malformed or oversized body, or an elapsed request bound
|
|
330
|
+
| `metadata` | a refused status, a redirect, a malformed or oversized body, a version reply that names no version, or an elapsed request bound |
|
|
332
331
|
| `unload` | an unload reply that doesn't confirm the declared model |
|
|
333
332
|
| `cleanup` | a termination that wasn't confirmed |
|
|
334
333
|
| `aborted` | a cancellation through `signal`, or a stop during startup or maintenance |
|
|
@@ -713,13 +712,13 @@ declare const MODEL_DIGEST: string
|
|
|
713
712
|
declare const WORKSPACE: string
|
|
714
713
|
|
|
715
714
|
const daemon = createOllamaDaemon({
|
|
716
|
-
executable: { path: OLLAMA_PATH, digest: OLLAMA_DIGEST
|
|
715
|
+
executable: { path: OLLAMA_PATH, digest: OLLAMA_DIGEST },
|
|
717
716
|
url: 'http://127.0.0.1:11437',
|
|
718
717
|
models: [{ name: 'qwen3.5:2b-q4_K_M', digest: MODEL_DIGEST }],
|
|
719
718
|
workspace: WORKSPACE,
|
|
720
719
|
})
|
|
721
720
|
try {
|
|
722
|
-
const identity = await daemon.start() // the verified receipt: executable, url, pid, and models
|
|
721
|
+
const identity = await daemon.start() // the verified receipt: executable, url, pid, the reported version, and models
|
|
723
722
|
const provider = createOllama({ model: 'qwen3.5:2b-q4_K_M', url: daemon.url })
|
|
724
723
|
const answer = await provider.generate(
|
|
725
724
|
[{ id: '1', role: 'user', content: 'Reply with exactly: ok' }],
|
|
@@ -747,7 +746,7 @@ isOllamaOrigin('http://127.0.0.1:11434') // false — the default port is never
|
|
|
747
746
|
isOllamaOrigin('http://localhost:11437') // false — the origin names 127.0.0.1 exactly
|
|
748
747
|
|
|
749
748
|
const declaration = {
|
|
750
|
-
executable: { path: '/opt/ollama/bin/ollama', digest: 'a'.repeat(64)
|
|
749
|
+
executable: { path: '/opt/ollama/bin/ollama', digest: 'a'.repeat(64) },
|
|
751
750
|
url: 'http://127.0.0.1:11437',
|
|
752
751
|
models: [{ name: 'qwen3.5:2b-q4_K_M', digest: 'b'.repeat(64) }],
|
|
753
752
|
workspace: '/srv/ollama',
|
|
@@ -843,10 +842,10 @@ The judge proofs cover the recorded wire and the live models.
|
|
|
843
842
|
|
|
844
843
|
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.
|
|
845
844
|
|
|
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.
|
|
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
|
|
845
|
+
- [`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, a startup across a version the declaration never named that records the reported version, 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.
|
|
846
|
+
- [`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 reader and the model comparison, 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.
|
|
848
847
|
- [`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.
|
|
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
|
|
848
|
+
- [`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 the selected model's `/api/tags` digest, and chooses an ephemeral loopback port apart from 11434 and the provisioned service port. The proof compares no versions, so the executable can be another build than the one the provisioned service runs, and the receipt records the version the dedicated daemon reports. It runs only in the `service` project.
|
|
850
849
|
|
|
851
850
|
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.
|
|
852
851
|
|