@orkestrel/scaffold 0.0.129 → 0.0.130
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/bin/main.js +1 -1
- package/dist/host/agents/orchestration.md +1 -0
- package/dist/host/agents/skills/orkestrel-parallel/references/t3.md +1 -0
- package/dist/host/claude/agents/orkestrel.md +3 -3
- package/dist/host/guides/capture.md +5 -5
- package/dist/host/guides/middleware.md +82 -64
- package/dist/host/manifest.json +6 -6
- package/dist/src/core/index.cjs +56 -12
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.js +56 -12
- package/dist/src/core/index.js.map +1 -1
- package/package.json +1 -1
package/dist/bin/main.js
CHANGED
|
@@ -10,7 +10,7 @@ import { readdirSync } from "node:fs";
|
|
|
10
10
|
import { parseArgs } from "node:util";
|
|
11
11
|
var package_default = {
|
|
12
12
|
name: "@orkestrel/scaffold",
|
|
13
|
-
version: "0.0.
|
|
13
|
+
version: "0.0.130",
|
|
14
14
|
description: "Scaffold workspaces with commands: new, audit, surface, repair, catalog, and overwrite.",
|
|
15
15
|
keywords: [
|
|
16
16
|
"audit",
|
|
@@ -88,6 +88,7 @@ The harness's own engine orchestrates: Claude Fable 5.2 or Claude Opus 5.5 in Cl
|
|
|
88
88
|
## Pace
|
|
89
89
|
|
|
90
90
|
- Spend process only where it changes a result. Launch, run, and report: no fixed clock windows, readiness-only turns, per-command acknowledgments, hash pins of a brief, or process queries beyond the recorded process ids.
|
|
91
|
+
- When no acceptance check reads a run's result anymore, stop the run.
|
|
91
92
|
- When a verifier lane fails in its harness rather than in the gate, run the gate once yourself and read its exit code; write no comparator, snapshot, or retry chain to obtain evidence.
|
|
92
93
|
- Keep valid receipts. Re-run a check only when a change to its inputs, configuration, environment, or claim could alter what it proved, and then run the narrowest check that covers the change. Never repeat a passing check to collect another receipt or to have every suite pass in one command; name the receipt that covers each check a brief does not rerun.
|
|
93
94
|
- Ask the user only for a decision that is theirs: scope, the spend ceiling and stop line § Hold the plan names, a conflicting ruling, a credential, publication, or a commit or push the law reserves. Decide routine matters yourself, such as time and lane allowances, retries, and order, and report them, with time in whole minutes.
|
|
@@ -26,6 +26,7 @@ T3 hosts Claude, Codex, and Cursor lanes as app-owned child tasks of a thread, a
|
|
|
26
26
|
- When a launch's reply is missing or ambiguous, inspect the recorded task before retrying. A timeout on a parent wait cancels no child work.
|
|
27
27
|
- When a send carries a consequential message, use `auto` and read the target to confirm it arrived: a `queue` send reported as queued, on a run that had already completed, never reached its target (2026-11-05).
|
|
28
28
|
- When a child's status reads completed, read its thread and the process list before acting on that status: its background shell can wake it for another turn. Check a child's claim about its own shell the same way (2026-11-05).
|
|
29
|
+
- When a child ends its turn while a background command it started still runs, wait for the `delegated-task:provider-continuation` notification that command's exit delivers to the parent, carrying the child's next report; never relaunch the child or poll its thread for it (2026-11-10).
|
|
29
30
|
- When a finished child still holds servers past the idle stop, stop them by recorded process id, and read `.agents/platforms/` for what each child costs on the host.
|
|
30
31
|
- When a thread shows a nonzero `pendingRequestCount` and `t3_pending_request` lists nothing, read it as an approval nobody can answer, because that tool lists no approvals (2026-11-06).
|
|
31
32
|
- When a lane must be interrupted and restarted, use `restart`; never use it as a resume. Create no ordinary top-level thread as a delegated lane.
|
|
@@ -48,7 +48,7 @@ Treat generated package identifiers, versions, layers, and dependency ranges as
|
|
|
48
48
|
| `@orkestrel/brief` | `0.0.17` | L4 | `@orkestrel/reason` `^0.0.17`, `@orkestrel/emitter` `^0.0.15`, `@orkestrel/contract` `^0.0.22`, `@orkestrel/interpret` `^0.0.22` | |
|
|
49
49
|
| `@orkestrel/browser` | `0.0.32` | L5 | `@orkestrel/mcp` `^0.0.42`, `@orkestrel/html` `^0.0.15`, `@orkestrel/pool` `^0.0.20`, `@orkestrel/tool` `^0.0.22`, `@orkestrel/codec` `^0.0.9`, `@orkestrel/router` `^0.0.20`, `@orkestrel/server` `^0.0.26`, `@orkestrel/emitter` `^0.0.15`, `@orkestrel/process` `^0.0.18`, `@orkestrel/contract` `^0.0.22`, `@orkestrel/markdown` `^0.0.20`, `@orkestrel/websocket` `^0.0.18` | |
|
|
50
50
|
| `@orkestrel/budget` | `0.0.17` | L1 | `@orkestrel/contract` `^0.0.22` | |
|
|
51
|
-
| `@orkestrel/capture` | `0.0.
|
|
51
|
+
| `@orkestrel/capture` | `0.0.6` | L3 | `@orkestrel/process` `^0.0.18`, `@orkestrel/timeout` `^0.0.16`, `@orkestrel/contract` `^0.0.22` | `vite` `^8.3.7`, `vitest` `^4.1.12 \|\| ^5.1.0`, `playwright` `^1.61.0`, `@vitest/browser-playwright` `^4.1.12 \|\| ^5.0.5` |
|
|
52
52
|
| `@orkestrel/codec` | `0.0.9` | L1 | `@orkestrel/contract` `^0.0.22` | |
|
|
53
53
|
| `@orkestrel/console` | `0.0.19` | L2 | `@orkestrel/emitter` `^0.0.15`, `@orkestrel/contract` `^0.0.22` | |
|
|
54
54
|
| `@orkestrel/contract` | `0.0.22` | L0 | | |
|
|
@@ -64,7 +64,7 @@ Treat generated package identifiers, versions, layers, and dependency ranges as
|
|
|
64
64
|
| `@orkestrel/lsp` | `0.0.14` | L3 | `@orkestrel/emitter` `^0.0.15`, `@orkestrel/jsonrpc` `^0.0.2`, `@orkestrel/process` `^0.0.18`, `@orkestrel/contract` `^0.0.22` | |
|
|
65
65
|
| `@orkestrel/markdown` | `0.0.20` | L2 | `@orkestrel/html` `^0.0.15`, `@orkestrel/contract` `^0.0.22` | |
|
|
66
66
|
| `@orkestrel/mcp` | `0.0.42` | L4 | `@orkestrel/sse` `^0.0.13`, `@orkestrel/tool` `^0.0.22`, `@orkestrel/codec` `^0.0.9`, `@orkestrel/emitter` `^0.0.15`, `@orkestrel/jsonrpc` `^0.0.2`, `@orkestrel/process` `^0.0.18`, `@orkestrel/contract` `^0.0.22`, `@orkestrel/websocket` `^0.0.18` | `@orkestrel/router` `^0.0.20`, `@orkestrel/server` `^0.0.26` |
|
|
67
|
-
| `@orkestrel/middleware` | `0.0.
|
|
67
|
+
| `@orkestrel/middleware` | `0.0.30` | L4 | `@orkestrel/abort` `^0.0.16`, `@orkestrel/budget` `^0.0.17`, `@orkestrel/timeout` `^0.0.16`, `@orkestrel/contract` `^0.0.22` | `@orkestrel/server` `^0.0.26`, `@orkestrel/database` `^0.0.22` |
|
|
68
68
|
| `@orkestrel/msg` | `0.0.16` | L2 | `@orkestrel/codec` `^0.0.9`, `@orkestrel/contract` `^0.0.22` | |
|
|
69
69
|
| `@orkestrel/ndjson` | `0.0.16` | L1 | `@orkestrel/contract` `^0.0.22` | |
|
|
70
70
|
| `@orkestrel/ollama` | `0.0.33` | L6 | `@orkestrel/tool` `^0.0.22`, `@orkestrel/agent` `^0.0.39`, `@orkestrel/budget` `^0.0.17`, `@orkestrel/ndjson` `^0.0.16`, `@orkestrel/emitter` `^0.0.15`, `@orkestrel/process` `^0.0.18`, `@orkestrel/contract` `^0.0.22` | |
|
|
@@ -78,7 +78,7 @@ Treat generated package identifiers, versions, layers, and dependency ranges as
|
|
|
78
78
|
| `@orkestrel/reason` | `0.0.17` | L2 | `@orkestrel/emitter` `^0.0.15`, `@orkestrel/contract` `^0.0.22` | |
|
|
79
79
|
| `@orkestrel/relation` | `0.0.20` | L3 | `@orkestrel/emitter` `^0.0.15`, `@orkestrel/contract` `^0.0.22`, `@orkestrel/database` `^0.0.22` | |
|
|
80
80
|
| `@orkestrel/router` | `0.0.20` | L2 | `@orkestrel/abort` `^0.0.16`, `@orkestrel/emitter` `^0.0.15`, `@orkestrel/contract` `^0.0.22` | |
|
|
81
|
-
| `@orkestrel/scaffold` | `0.0.
|
|
81
|
+
| `@orkestrel/scaffold` | `0.0.129` | L3 | `@orkestrel/console` `^0.0.19`, `@orkestrel/emitter` `^0.0.15`, `@orkestrel/process` `^0.0.18`, `@orkestrel/contract` `^0.0.22`, `@orkestrel/markdown` `^0.0.20`, `@orkestrel/template` `^0.0.13` | |
|
|
82
82
|
| `@orkestrel/sea` | `0.0.22` | L3 | `@orkestrel/emitter` `^0.0.15`, `@orkestrel/process` `^0.0.18`, `@orkestrel/contract` `^0.0.22` | |
|
|
83
83
|
| `@orkestrel/server` | `0.0.26` | L3 | `@orkestrel/abort` `^0.0.16`, `@orkestrel/codec` `^0.0.9`, `@orkestrel/router` `^0.0.20`, `@orkestrel/emitter` `^0.0.15`, `@orkestrel/timeout` `^0.0.16`, `@orkestrel/contract` `^0.0.22` | |
|
|
84
84
|
| `@orkestrel/sqlite` | `0.0.17` | L1 | `@orkestrel/contract` `^0.0.22` | |
|
|
@@ -229,7 +229,7 @@ Engine, runner, preflight, and contact-sheet contracts from [`types.ts`](../src/
|
|
|
229
229
|
| `CaptureSheetsInterface` | interface | `{ execute() }` | Composes exactly the authenticated sparse state and output pairs for iteration review. |
|
|
230
230
|
| `CaptureRegistryArguments` | interface | `{ config, variants, mode? }` | Carries the parsed registry command line: the wrapper, the variants to refresh, and the mode. |
|
|
231
231
|
| `CaptureRegistrarOptions` | interface | `{ root, config, requests, argv, stdout?, stderr?, deadline? }` | Configures one registry refresh: its workspace, wrapper default, request directory, and command line. |
|
|
232
|
-
| `CaptureRegistrarInterface` | interface | `{ execute() }` | Refreshes the accepted registry from one complete capture-free journey
|
|
232
|
+
| `CaptureRegistrarInterface` | interface | `{ execute() }` | Refreshes the accepted registry from one complete capture-free journey stage over the selected variants. |
|
|
233
233
|
| `CaptureInputHandler` | type | `(file: string) => string \| undefined` | Reads a contained input through an owning operation's file snapshot memo. |
|
|
234
234
|
| `CaptureRetractionHandler` | type | `() => void` | Removes one invocation's published request during shutdown. |
|
|
235
235
|
| `CaptureTerminationHandler` | type | `() => Promise<boolean>` | Begins one independent child termination only after request removal has been attempted. |
|
|
@@ -257,7 +257,7 @@ The runner's names and bounds from [`constants.ts`](../src/server/constants.ts).
|
|
|
257
257
|
| `CAPTURE_REPORT_LINES` | const | `Readonly<{ readonly preflight: 'READER'; readonly sheets: 'SHEETS'; }>` | Names the first word of the line a reader prints, followed by its JSON report. |
|
|
258
258
|
| `CAPTURE_SHEET` | const | `Readonly<{ readonly cell: 320; readonly limit: 400; readonly mark: Readonly<{ width: 160; height: 20; present: 220; absent: 20; }>; readonly gap: 12; readonly pairs: 2; readonly rows: 4; }>` | Holds the contact-sheet geometry: how wide a cell shrinks toward, how tall it may grow, the mark that stands in for an unreadable image, the gap between neighbors, and how many cells, rows, and pairs a row and a sheet hold. |
|
|
259
259
|
| `CAPTURE_SHEET_FILES` | const | `Readonly<{ readonly prefix: 'sheet-'; readonly digits: 3; readonly index: 'index.json'; readonly notes: 'index.md'; }>` | Names the contact-sheet files: the sheet prefix and digits, and the two index documents. |
|
|
260
|
-
| `CAPTURE_REGISTRY_STAGE` | const | `"registry"` | Names the stage
|
|
260
|
+
| `CAPTURE_REGISTRY_STAGE` | const | `"registry"` | Names the one stage a registry refresh runs every selected producing variant's complete journey in. |
|
|
261
261
|
| `CAPTURE_REGISTRY_LINE` | const | `"REGISTRY"` | Names the first word of the line the registry refresh prints, followed by its JSON summary. |
|
|
262
262
|
| `CAPTURE_REQUESTS_FLAG` | const | `"CAPTURE_REQUESTS"` | Names the environment variable that carries the absolute request directory to a Vitest child. |
|
|
263
263
|
| `CAPTURE_DISCOVERY` | const | `Readonly<{ readonly phase: 'discover'; readonly description: 'description.json'; readonly arguments: readonly string[]; readonly deadline: 60000; }>` | Holds the discovery exchange's fixed names and bound. |
|
|
@@ -365,7 +365,7 @@ The integrity engine from [`CaptureIntegrity.ts`](../src/server/CaptureIntegrity
|
|
|
365
365
|
| `CaptureSheets` | class | `new (options: CaptureSheetOptions) => CaptureSheetsInterface` | Composes exactly the authenticated sparse state and output pairs for iteration review. |
|
|
366
366
|
| `createCapturePreflight` | function | `(options: CaptureReaderOptions) => CapturePreflightInterface` | Creates the preflight that judges the selected frames' freshness, mixed observations, and coverage. |
|
|
367
367
|
| `createCaptureSheets` | function | `(options: CaptureSheetOptions) => CaptureSheetsInterface` | Creates the contact-sheet writer for the selected frames. |
|
|
368
|
-
| `CaptureRegistrar` | class | `new (options: CaptureRegistrarOptions) => CaptureRegistrarInterface` | Refreshes the accepted registry from one complete capture-free journey
|
|
368
|
+
| `CaptureRegistrar` | class | `new (options: CaptureRegistrarOptions) => CaptureRegistrarInterface` | Refreshes the accepted registry from one complete capture-free journey stage over the selected variants. |
|
|
369
369
|
| `createCaptureRegistrar` | function | `(options: CaptureRegistrarOptions) => CaptureRegistrarInterface` | Creates the registry refresh that runs each producing variant's complete journey and publishes the registry. |
|
|
370
370
|
| `CaptureCLI` | class | `new (options?: CaptureCLIOptions) => CaptureCLIInterface` | Dispatches capture commands and maps usage and evidence refusals to their exit codes. |
|
|
371
371
|
| `createCaptureCLI` | function | `(options?: CaptureCLIOptions) => CaptureCLIInterface` | Creates the executable's command dispatcher over a workspace and injected writers. |
|
|
@@ -646,7 +646,7 @@ A module that cannot be loaded, exports no list of functions, or holds a reader
|
|
|
646
646
|
|
|
647
647
|
### Registry refresh
|
|
648
648
|
|
|
649
|
-
The command that bootstraps or replaces the accepted registry. The stage transaction refuses to run until a registry exists, so the refresh cannot stamp through the engine: it imports complete runs instead. `createCaptureRegistrar` takes the same options as the runner minus the command, and `execute` reads the wrapper through the same `CaptureDiscovery` the runner uses, forwarding `--mode` to discovery, the factory, and
|
|
649
|
+
The command that bootstraps or replaces the accepted registry. The stage transaction refuses to run until a registry exists, so the refresh cannot stamp through the engine: it imports complete runs instead. `createCaptureRegistrar` takes the same options as the runner minus the command, and `execute` reads the wrapper through the same `CaptureDiscovery` the runner uses, forwarding `--mode` to discovery, the factory, and the execution child. It takes the same invocation entity and request file, and runs every selected producing variant in one stage, one Vitest child that receives each variant's project, with the `all` selector, the `journey` command, and no capture variable.
|
|
650
650
|
|
|
651
651
|
Refresh a selected producing variant through the registrar:
|
|
652
652
|
|
|
@@ -666,7 +666,7 @@ const exit = await registrar.execute() // 0 when the registry was published
|
|
|
666
666
|
|
|
667
667
|
**Inherited evidence.** Before any stage, the command reads an existing manifest and lookup journal and checks their schemas. An unreadable or unsupported document refuses the refresh and names the file to inspect and repair before retrying. Publication still authenticates inherited evidence through the integrity engine.
|
|
668
668
|
|
|
669
|
-
**Stages.** The stage
|
|
669
|
+
**Stages.** The one stage is named `registry`, so its reporter is `<requests>/runs/<id>/registry.json` and each variant's record is `<directory>/runs/<id>/registry/<variant>.json`. A partial refresh runs only the named variants in that stage. The command takes each selected project's declared input population and its content hashes before the child starts and again after, and refuses when they differ. A child that exits unsuccessfully refuses the refresh with a message that names the stage and its variants. The command then reads the reporter once and, for each variant, reads the final record, requires it to carry the stage's own request, to name the variant, to fall between the start of the refresh and the end of the reporter, to agree with every collected declaration of that variant, and to be complete, and builds one receipt from them: the variant, the record's time, the reporter's path and digest, the input hashes, and the record's declarations and registry. Every receipt the stage builds names the same reporter and digest.
|
|
670
670
|
|
|
671
671
|
**Publication.** `buildCaptureRegistry` imports the receipts only after each exit is zero and each reporter digest still equals its receipt. The registry is written to a candidate beside `registry.json`, read back through the integrity engine pointed at the candidate, and only then renamed over the target, so a registry the engine would refuse never replaces a good one and the old bytes survive a failed or interrupted refresh. The command prints one `REGISTRY` line of JSON: the file, the digest, the variants in the registry, the variants this run refreshed, and the entry count.
|
|
672
672
|
|
|
@@ -55,8 +55,8 @@ const handle = compose<State>([boundary, security], async (_request, context) =>
|
|
|
55
55
|
| `createDeadline` | function | `<TState>(options: DeadlineOptions) => MiddlewareHandler<TState>` | Creates the application-level per-request deadline battery. |
|
|
56
56
|
| `createForwarded` | function | `<TState extends ClientState & ConnectionState>(options: ForwardedOptions) => MiddlewareHandler<TState>` | Creates the trusted-proxy client-IP resolver battery — walks `X-Forwarded-For` past the hops its options declare trusted. |
|
|
57
57
|
| `createETag` | function | `<TState>(options?: ETagOptions) => MiddlewareHandler<TState>` | Creates the dynamic response `ETag` + conditional GET battery (RFC 7232). |
|
|
58
|
-
| `createBearer` | function | `<TState extends BearerState>(options: BearerOptions) => MiddlewareHandler<TState>`
|
|
59
|
-
| `createLimiter` | function | `<TState extends BearerState & ClientState & ConnectionState>(options: LimiterOptions<TState>) => MiddlewareHandler<TState>`
|
|
58
|
+
| `createBearer` | function | `<TState extends BearerState<TCredential>, TCredential = string>(options: BearerOptions<TCredential>) => MiddlewareHandler<TState>` | Creates the bearer-token authentication battery — reads the token from its header, resolves its credential through `verify`, and answers each `401` with a `WWW-Authenticate` challenge. |
|
|
59
|
+
| `createLimiter` | function | `<TState extends BearerState<unknown> & ClientState & ConnectionState>(options: LimiterOptions<TState>) => MiddlewareHandler<TState>` | Creates the fixed-window rate-limiting battery — checks a key's budget before consuming it, so one window admits exactly `max` requests. |
|
|
60
60
|
| `createBody` | function | `<TState extends BodyState = BodyState>() => MiddlewareHandler<TState>` | Creates the body-driving battery — eagerly awaits the cached `context.body()` so its throws (or a malformed-JSON `undefined`) surface before the handler runs, and stashes the resolved value onto `BodyState.body`. |
|
|
61
61
|
| `createSession` | function | `<S extends SessionInterface = SessionInterface, TState extends SessionState & ConnectionState = SessionState & ConnectionState>(options: SessionOptions<S, TState>) => MiddlewareHandler<TState>` | Creates the generic session battery — resolves, mints, and persists a session across the request, with a mid-handler `regenerate`/`destroy` control handle. |
|
|
62
62
|
| `createCSRF` | function | `<TState extends CSRFState & SessionState & ConnectionState>(options: CSRFOptions) => MiddlewareHandler<TState>` | Creates the session-bound double-submit CSRF protection battery. |
|
|
@@ -74,60 +74,61 @@ const handle = compose<State>([boundary, security], async (_request, context) =>
|
|
|
74
74
|
|
|
75
75
|
### Types
|
|
76
76
|
|
|
77
|
-
| Name | Kind | Signature
|
|
78
|
-
| --------------------------- | --------- |
|
|
79
|
-
| `BoundaryOptions` | interface | `{ expose?, report? }`
|
|
80
|
-
| `TelemetryEntry` | interface | `{ method, pathname, status, duration }`
|
|
81
|
-
| `TelemetryOptions` | interface | `{ record }`
|
|
82
|
-
| `CompressionOptions` | interface | `{ threshold?, encodings?, filter? }`
|
|
83
|
-
| `CompressResponseOptions` | interface | `{ threshold, filter?, encodings, compress }`
|
|
84
|
-
| `SecurityIdentifierOptions` | type | `{ readonly trust?: boolean; } \| false`
|
|
85
|
-
| `SecurityOptions` | interface | `{ frame?, csp?, referrer?, permissions?, coop?, corp?, cluster?, coep?, hsts?, identifier? }`
|
|
86
|
-
| `CorsOptions` | interface | `{ origin?, methods?, headers? }`
|
|
87
|
-
| `DeadlineOptions` | interface | `{ ms, status? }`
|
|
88
|
-
| `ForwardedOptions` | type | `{ readonly proxies: number; } \| { readonly trusted: readonly string[]; }`
|
|
89
|
-
| `ETagOptions` | interface | `{ weak? }`
|
|
90
|
-
| `BearerOptions` | interface | `{
|
|
91
|
-
| `
|
|
92
|
-
| `
|
|
93
|
-
| `
|
|
94
|
-
| `
|
|
95
|
-
| `
|
|
96
|
-
| `
|
|
97
|
-
| `
|
|
98
|
-
| `
|
|
99
|
-
| `
|
|
100
|
-
| `
|
|
101
|
-
| `
|
|
102
|
-
| `
|
|
103
|
-
| `
|
|
104
|
-
| `
|
|
105
|
-
| `
|
|
106
|
-
| `
|
|
107
|
-
| `
|
|
108
|
-
| `
|
|
109
|
-
| `
|
|
110
|
-
| `
|
|
111
|
-
| `
|
|
112
|
-
| `
|
|
113
|
-
| `
|
|
114
|
-
| `
|
|
115
|
-
| `
|
|
116
|
-
| `
|
|
117
|
-
| `
|
|
118
|
-
| `
|
|
119
|
-
| `
|
|
120
|
-
| `
|
|
121
|
-
| `
|
|
122
|
-
| `
|
|
123
|
-
| `
|
|
124
|
-
| `
|
|
125
|
-
| `
|
|
126
|
-
| `
|
|
127
|
-
| `
|
|
128
|
-
| `
|
|
129
|
-
| `
|
|
130
|
-
| `
|
|
77
|
+
| Name | Kind | Signature | Summary |
|
|
78
|
+
| --------------------------- | --------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
79
|
+
| `BoundaryOptions` | interface | `{ expose?, report? }` | Configures `createBoundary` — the outermost error-rendering battery. |
|
|
80
|
+
| `TelemetryEntry` | interface | `{ method, pathname, status, duration }` | Represents one access-log-style entry `createTelemetry` records after a response settles — the access-log/timing seam's payload shape. |
|
|
81
|
+
| `TelemetryOptions` | interface | `{ record }` | Configures `createTelemetry` — the request timing/access-log seam. |
|
|
82
|
+
| `CompressionOptions` | interface | `{ threshold?, encodings?, filter? }` | Configures `createCompression` — response-body compression. |
|
|
83
|
+
| `CompressResponseOptions` | interface | `{ threshold, filter?, encodings, compress }` | Describes the already-resolved settings `compressResponse` runs its shared negotiate → skip → threshold → compress skeleton against — the shape each of `createCompression` and `createNodeCompression` builds from its own option bag. |
|
|
84
|
+
| `SecurityIdentifierOptions` | type | `{ readonly trust?: boolean; } \| false` | Describes `createSecurity`'s `identifier` sub-option — request-id minting/echo policy, or `false` to disable the feature entirely. |
|
|
85
|
+
| `SecurityOptions` | interface | `{ frame?, csp?, referrer?, permissions?, coop?, corp?, cluster?, coep?, hsts?, identifier? }` | Configures `createSecurity` — the security-headers + request-id battery. |
|
|
86
|
+
| `CorsOptions` | interface | `{ origin?, methods?, headers? }` | Configures `createCors` — Cross-Origin Resource Sharing. |
|
|
87
|
+
| `DeadlineOptions` | interface | `{ ms, status? }` | Configures `createDeadline` — the application-level per-request deadline. |
|
|
88
|
+
| `ForwardedOptions` | type | `{ readonly proxies: number; } \| { readonly trusted: readonly string[]; }` | Configures `createForwarded` — the trusted-proxy client-IP resolver. |
|
|
89
|
+
| `ETagOptions` | interface | `{ weak? }` | Configures `createETag` — dynamic response ETag + conditional GET. |
|
|
90
|
+
| `BearerOptions` | interface | `{ verify, header?, scheme?, challenge? }` | Configures `createBearer` — bearer-token authentication. |
|
|
91
|
+
| `BearerVerifyFunction` | type | `(token: string, request: Request) => TCredential \| undefined \| Promise<TCredential \| undefined>` | Verifies a presented bearer token and resolves its credential, or `undefined` to refuse it. |
|
|
92
|
+
| `LimiterOptions` | interface | `{ store?, max, window, capacity?, key?, message?, clock?, policy?, evict? }` | Configures `createLimiter` — fixed-window rate limiting. |
|
|
93
|
+
| `BearerState` | interface | `{ token? }` | Describes the bearer-authentication state slice `createBearer` stashes on `context.state` once a token verifies. |
|
|
94
|
+
| `IdentifierState` | interface | `{ identifier? }` | Describes the request-identifier state slice `createSecurity` stashes when its `identifier` option is enabled. |
|
|
95
|
+
| `Client` | interface | `{ ip? }` | Describes the resolved client connection facts `createForwarded` stashes. |
|
|
96
|
+
| `ClientState` | interface | `{ client? }` | Describes the client-facts state slice `createForwarded` stashes. |
|
|
97
|
+
| `ConnectionState` | interface | `{ connection? }` | Describes the connection-facts state slice `createLimiter`'s default key derivation falls back to when neither `BearerState` nor `ClientState` is present — the raw socket peer surfaced on `context.state` by the server's `state` option. |
|
|
98
|
+
| `SessionInterface` | interface | `{ id, state, set(), delete(), clear() }` | Represents a server-managed session's public surface — an id, its live state, and the mutators that write it. |
|
|
99
|
+
| `SessionControlInterface` | interface | `{ destroyed, successor, regenerate(), destroy() }` | Describes the mid-handler control handle `createSession` stashes alongside the session itself — the OWASP anti-fixation / logout primitives. |
|
|
100
|
+
| `SessionState` | interface | `{ session?, control? }` | Describes the session state slice `createSession` stashes. |
|
|
101
|
+
| `BodyState` | interface | `{ body? }` | Describes the body state slice `createBody` stashes. |
|
|
102
|
+
| `SessionStoreInterface` | interface | `{ get(), set(), delete() }` | Describes the pluggable session persistence seam `createSession`'s `store` option implements — a point-access store keyed by session id. |
|
|
103
|
+
| `SessionTransportInterface` | interface | `{ read(), write(), clear() }` | Describes the transport seam `createSession`'s `transport` option implements — how a session id travels to and from the client (a signed cookie, a header, …). |
|
|
104
|
+
| `SessionOptions` | interface | `{ transport, store?, ttl?, lifetime?, capacity?, evict?, create?, mint?, required?, clock? }` | Configures `createSession` — the generic session battery. |
|
|
105
|
+
| `CookieTransportOptions` | interface | `{ name?, secret, cookie? }` | Configures `createCookieTransport` — the signed-cookie `SessionTransportInterface`. |
|
|
106
|
+
| `HeaderTransportOptions` | interface | `{ header? }` | Configures `createHeaderTransport` — the bare-header `SessionTransportInterface`. |
|
|
107
|
+
| `MemorySessionStoreOptions` | interface | `{ capacity?, evict? }` | Configures `createMemorySessionStore` — the default in-process `SessionStoreInterface`. |
|
|
108
|
+
| `SessionLimits` | interface | `{ ttl?, lifetime? }` | Describes the idle and absolute-lifetime thresholds a session store enforces — `sessionExpired`'s limits argument and both shipped stores' construction options. |
|
|
109
|
+
| `SessionCursors` | interface | `{ seen, created }` | Describes the per-session instants a store stamps and `sessionExpired` measures against. |
|
|
110
|
+
| `SessionRow` | interface | `{ id, session }` | Represents one persisted session row — an opaque snapshot column plus the store-owned idle/absolute-lifetime cursors, the shape a `DatabaseSessionStore`'s backing table holds. |
|
|
111
|
+
| `SessionEntry` | interface | `{ session }` | Represents one in-process session entry — the payload `MemorySessionStore` holds against an id, alongside the same cursors a persisted row carries. |
|
|
112
|
+
| `SessionSnapshot` | interface | `{ id, state }` | Represents a session's serializable projection — the value `snapshotSession` produces and a durable store's `set` writes. |
|
|
113
|
+
| `SessionRestoreFunction` | type | `(value: unknown) => SessionInterface \| undefined` | Rebuilds a session entity from an untrusted stored snapshot, or resolves `undefined` when the value is malformed. |
|
|
114
|
+
| `CSRFState` | interface | `{ csrf? }` | Describes the CSRF state slice `createCSRF` stashes — the raw token a safe-method response exposes for a subsequent mutating request to submit back. |
|
|
115
|
+
| `CSRFOptions` | interface | `{ secret, cookie?, header?, field?, safe? }` | Configures `createCSRF` — session-bound double-submit CSRF protection. |
|
|
116
|
+
| `MultipartFile` | interface | `{ field, name, size, mime, validated, status, path }` | Represents one staged multipart upload's public record — the shape the node-face `createMultipart` battery (`@orkestrel/middleware/server`) produces per uploaded file. |
|
|
117
|
+
| `MultipartBody` | interface | `{ files, fields }` | Describes the parsed multipart request body `createMultipart` stashes — files keyed by their field name, plus every plain text field. |
|
|
118
|
+
| `MultipartState` | interface | `{ multipart? }` | Describes the multipart state slice `createMultipart` stashes. |
|
|
119
|
+
| `AssetRepresentation` | interface | `{ body, encoding? }` | Describes one in-memory asset representation returned by an `AssetSourceInterface`. |
|
|
120
|
+
| `AssetSourceInterface` | interface | `{ read() }` | Reads in-memory assets by decoded, browser-build-relative path. |
|
|
121
|
+
| `AssetOptions` | interface | `{ source, store? }` | Configures `createAssets` — in-memory identity/Brotli asset serving. |
|
|
122
|
+
| `StaticOptions` | interface | `{ root, prefix?, index?, dotfiles?, cache?, etag?, fallback? }` | Configures `createStatic` — node `fs`-backed static file serving. |
|
|
123
|
+
| `MultipartLimitsInput` | interface | `{ file?, field?, total? }` | Describes the caller's partial `MultipartLimits` — `createMultipart`'s `limits` option, with every member optional. |
|
|
124
|
+
| `MultipartLimits` | interface | `{ file, field, total }` | Describes the per-category size/count caps `createMultipart` enforces mid-stream — the effective limits, every documented default already applied. |
|
|
125
|
+
| `MultipartOptions` | interface | `{ limits?, allowed?, directory? }` | Configures `createMultipart` — node `fs`/`os`/`crypto`-backed streaming multipart upload parsing. |
|
|
126
|
+
| `NodeCompressionOptions` | interface | `{ threshold?, filter? }` | Configures `createNodeCompression` — `node:zlib`-backed response compression. |
|
|
127
|
+
| `MultipartErrorCode` | type | `'limit' \| 'malformed' \| 'rejected'` | Names the reason `createMultipart` rejected a request — the machine-readable code `MultipartError` carries and maps onto its HTTP status: `'limit'` → 413, `'malformed'` → 400, `'rejected'` → 415. |
|
|
128
|
+
| `UploadStatus` | type | `'staged' \| 'moved'` | Names the lifecycle stage of one staged upload's temp file. |
|
|
129
|
+
| `UploadedFile` | interface | `{ status }` | Describes one uploaded file's post-parse record — the node-bound, richer sibling of the pure core's `MultipartFile` (identical fields, `status` narrowed to `UploadStatus`). Structurally assignable into `MultipartFile` so a `createMultipart`-built `MultipartBody` satisfies the shared core shape. |
|
|
130
|
+
| `PartHeaders` | interface | `{ name, filename, mime }` | Describes one multipart part's parsed header block — `parsePartHeaders`'s return shape. |
|
|
131
|
+
| `ByteRange` | interface | `{ start, end }` | Describes one inclusive byte range over a file — `streamFile`'s optional `range` argument and the shape `createStatic` builds for a satisfiable `Range` request. |
|
|
131
132
|
|
|
132
133
|
### Store and response types
|
|
133
134
|
|
|
@@ -183,6 +184,8 @@ const handle = compose<State>([boundary, security], async (_request, context) =>
|
|
|
183
184
|
| `DEFAULT_DEADLINE_STATUS` | const | `503` | Holds `503`, the default response status `createDeadline` returns when its deadline fires first. |
|
|
184
185
|
| `DEFAULT_BEARER_HEADER` | const | `"authorization"` | Names `'authorization'`, the default header `createBearer` reads the token from. |
|
|
185
186
|
| `DEFAULT_BEARER_SCHEME` | const | `"Bearer"` | Names `'Bearer'`, the default scheme prefix `createBearer` strips before verification. |
|
|
187
|
+
| `CHALLENGE_TOKEN` | const | `Readonly<RegExp>` | Matches an RFC 9110 `token`, the form a challenge scheme and an auth-param name take. |
|
|
188
|
+
| `CHALLENGE_VALUE` | const | `Readonly<RegExp>` | Matches the characters RFC 6750 § 3 admits in a quoted auth-param value: `%x20-21 / %x23-5B / %x5D-7E`. |
|
|
186
189
|
| `DEFAULT_LIMITER_CAPACITY` | const | `10000` | Holds `10_000`, the default maximum number of distinct rate-limit keys `createLimiter` tracks before LRU eviction. |
|
|
187
190
|
| `DEFAULT_LIMITER_MESSAGE` | const | `"rate limit exceeded"` | Holds `'rate limit exceeded'`, the default 429 body message `createLimiter` sends when a key is over budget. |
|
|
188
191
|
| `DEFAULT_SESSION_CAPACITY` | const | `10000` | Holds `10_000`, the default maximum number of distinct session ids `createMemorySessionStore` tracks before LRU (by last write) eviction. |
|
|
@@ -219,7 +222,8 @@ const handle = compose<State>([boundary, security], async (_request, context) =>
|
|
|
219
222
|
|
|
220
223
|
| Name | Kind | Signature | Summary |
|
|
221
224
|
| ----------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
222
|
-
| `resolveKey` | function | `(state: BearerState & ClientState & ConnectionState) => string`
|
|
225
|
+
| `resolveKey` | function | `(state: BearerState<unknown> & ClientState & ConnectionState) => string` | Derives `createLimiter`'s default rate-limit bucket key from a request's resolved identity facts. |
|
|
226
|
+
| `renderChallenge` | function | `(scheme: string, parameters?: Readonly<Record<string, string>>) => string` | Renders a `WWW-Authenticate` challenge as the scheme alone, or the scheme followed by quoted auth-params in the record's own key order. |
|
|
223
227
|
| `resolveOptInHeader` | function | `(value: string \| boolean \| undefined, fallback: string) => string \| undefined` | Resolves an opt-in, value-bearing security header — `string \| boolean` (off by default, `true` uses the secure default), the shape `createSecurity`'s `coep`/`hsts` options use, distinct from the plain value-or-`false` shape `resolveSecurityHeader` (the peer substrate) handles. |
|
|
224
228
|
| `buildRetryAfter` | function | `(expiry: number, now: number) => string` | Builds the `Retry-After` header value — whole seconds until a window reset, floored at a minimum of `1`. |
|
|
225
229
|
| `buildRateLimitField` | function | `(remaining: number, expiry: number, now: number) => string` | Builds the draft `RateLimit` structured header field — emitted only when `createLimiter`'s `policy` option is `true`. |
|
|
@@ -450,8 +454,9 @@ prevents:
|
|
|
450
454
|
over the uncompressed representation — hashing the compressed bytes
|
|
451
455
|
would break revalidation the instant the negotiated coding changes.
|
|
452
456
|
11. **`createBearer` sits before `createLimiter`.** The limiter's default key
|
|
453
|
-
derivation prefers `BearerState.token` (the `token:<value>` idiom)
|
|
454
|
-
a client-IP fallback — bearer must have already stashed it.
|
|
457
|
+
derivation prefers a string `BearerState.token` (the `token:<value>` idiom)
|
|
458
|
+
over a client-IP fallback — bearer must have already stashed it. An object
|
|
459
|
+
credential never keys the limiter: the key falls through to the client address.
|
|
455
460
|
12. **`createBody` sits before `createSession`/`createCSRF`.** `createSession`'s
|
|
456
461
|
async `mint` and `createCSRF`'s `_csrf` body-field read both need the
|
|
457
462
|
cached `context.body()` already resolved.
|
|
@@ -469,9 +474,14 @@ prevents:
|
|
|
469
474
|
`crypto.randomUUID()` instead; a custom `csp` string replaces the
|
|
470
475
|
default wholesale (never merges); `X-Content-Type-Options: nosniff` is
|
|
471
476
|
unconditional, with no opt-out.
|
|
472
|
-
16. **Bearer.** `
|
|
473
|
-
|
|
474
|
-
|
|
477
|
+
16. **Bearer.** `createBearer` returns a `401` for a missing, wrong-scheme, or empty token
|
|
478
|
+
and for a credential `verify` refuses, and a throw from `verify` propagates
|
|
479
|
+
unchanged. With `verify: (token) => verifyToken(token, secret)`, `verifyToken` is
|
|
480
|
+
total over garbage, tampered, expired, or empty-rotation input — every failure
|
|
481
|
+
renders `401`, never a crash; verification is constant-time through
|
|
482
|
+
`crypto.subtle.verify`. The `401` is a returned response, so each outer
|
|
483
|
+
battery decorates it and `createBoundary`'s `report` never sees it; read
|
|
484
|
+
refusals from `createTelemetry`'s status.
|
|
475
485
|
17. **Limiter.** The key derivation never reads `X-Forwarded-For` itself (only
|
|
476
486
|
`createForwarded`'s already-resolved `ClientState` does, when mounted) —
|
|
477
487
|
so an unmounted `createForwarded` leaves XFF completely untrusted;
|
|
@@ -566,6 +576,14 @@ prevents:
|
|
|
566
576
|
fail-open. Whichever combinator is used, keep its path set in lockstep
|
|
567
577
|
with the router's actual routes — a route added after the fact and not
|
|
568
578
|
added to the set is silently unscoped.
|
|
579
|
+
26. **Challenge.** Every `401` `createBearer` returns carries a `WWW-Authenticate`
|
|
580
|
+
challenge (RFC 9110 § 15.5.2). A missing, wrong-scheme, or empty token renders
|
|
581
|
+
the configured `challenge` auth-params, and a refused credential adds
|
|
582
|
+
`error="invalid_token"` (RFC 6750 § 3). `renderChallenge` refuses a scheme or
|
|
583
|
+
parameter name that is not a `token`, two names that match ignoring case, and a
|
|
584
|
+
value outside `%x20-21 / %x23-5B / %x5D-7E`; it never escapes or strips. `createBearer`
|
|
585
|
+
refuses a `challenge` that names `error` at construction, because the battery
|
|
586
|
+
owns that parameter.
|
|
569
587
|
|
|
570
588
|
## Patterns
|
|
571
589
|
|
|
@@ -598,7 +616,7 @@ import type {
|
|
|
598
616
|
IdentifierState,
|
|
599
617
|
SessionState,
|
|
600
618
|
} from '@orkestrel/middleware'
|
|
601
|
-
import { compose } from '@orkestrel/server'
|
|
619
|
+
import { compose, verifyToken } from '@orkestrel/server'
|
|
602
620
|
|
|
603
621
|
interface State extends BearerState, ClientState, CSRFState, IdentifierState, SessionState {
|
|
604
622
|
readonly connection?: { readonly ip?: string }
|
|
@@ -613,7 +631,7 @@ const onion = [
|
|
|
613
631
|
createCors({ origin: ['https://app.example'] }),
|
|
614
632
|
createForwarded({ proxies: 1 }),
|
|
615
633
|
createETag(),
|
|
616
|
-
createBearer({
|
|
634
|
+
createBearer({ verify: (token) => verifyToken(token, 'shh') }),
|
|
617
635
|
createLimiter({ max: 100, window: 60_000 }),
|
|
618
636
|
createBody(),
|
|
619
637
|
createSession({ transport: createCookieTransport({ secret: 'shh' }) }),
|
package/dist/host/manifest.json
CHANGED
|
@@ -16,7 +16,7 @@
|
|
|
16
16
|
"storage": "agents/orchestration.md",
|
|
17
17
|
"destination": ".agents/orchestration.md",
|
|
18
18
|
"executable": false,
|
|
19
|
-
"digest": "
|
|
19
|
+
"digest": "67e49a59459fba935c1948d26c9b9fa48001e96d3b0fe0cee194ed724ea96c35"
|
|
20
20
|
},
|
|
21
21
|
{
|
|
22
22
|
"storage": "agents/platforms/posix.md",
|
|
@@ -430,7 +430,7 @@
|
|
|
430
430
|
"storage": "agents/skills/orkestrel-parallel/references/t3.md",
|
|
431
431
|
"destination": ".agents/skills/orkestrel-parallel/references/t3.md",
|
|
432
432
|
"executable": false,
|
|
433
|
-
"digest": "
|
|
433
|
+
"digest": "1669a45b33f53b6b560a65e64c0a13929e2703c4c907b87789518edf4c1b9a95"
|
|
434
434
|
},
|
|
435
435
|
{
|
|
436
436
|
"storage": "agents/skills/orkestrel-parallel/scripts/cases.ts",
|
|
@@ -628,7 +628,7 @@
|
|
|
628
628
|
"storage": "claude/agents/orkestrel.md",
|
|
629
629
|
"destination": ".claude/agents/orkestrel.md",
|
|
630
630
|
"executable": false,
|
|
631
|
-
"digest": "
|
|
631
|
+
"digest": "e6f261104a09bb01690031878c76254a83428ce2686b502b4a3d4cedaf4ec938"
|
|
632
632
|
},
|
|
633
633
|
{
|
|
634
634
|
"storage": "claude/agents/planner.md",
|
|
@@ -1018,7 +1018,7 @@
|
|
|
1018
1018
|
"storage": "guides/capture.md",
|
|
1019
1019
|
"destination": "guides/capture.md",
|
|
1020
1020
|
"executable": false,
|
|
1021
|
-
"digest": "
|
|
1021
|
+
"digest": "07c53b0e17c49a01d9d71546bebf0890f3d340f6cb3a86f8c99a7eafe8edb2bf"
|
|
1022
1022
|
},
|
|
1023
1023
|
{
|
|
1024
1024
|
"storage": "guides/codec.md",
|
|
@@ -1114,7 +1114,7 @@
|
|
|
1114
1114
|
"storage": "guides/middleware.md",
|
|
1115
1115
|
"destination": "guides/middleware.md",
|
|
1116
1116
|
"executable": false,
|
|
1117
|
-
"digest": "
|
|
1117
|
+
"digest": "dad75159938cd6179cc542a480b85e758043ba36d3f94a966f2bb42c3adb4049"
|
|
1118
1118
|
},
|
|
1119
1119
|
{
|
|
1120
1120
|
"storage": "guides/msg.md",
|
|
@@ -1417,5 +1417,5 @@
|
|
|
1417
1417
|
"scripts"
|
|
1418
1418
|
],
|
|
1419
1419
|
"surface": [],
|
|
1420
|
-
"digest": "
|
|
1420
|
+
"digest": "330a0fb610a98e81c08d3eec813975d3fd59ee6a22db45d3381df695245e0079"
|
|
1421
1421
|
}
|