@orkestrel/tool 0.0.3 → 0.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@orkestrel/tool",
-	"version": "0.0.3",
+	"version": "0.0.5",
 	"description": "Concrete LLM-callable tools for the @orkestrel line — workflow authoring, workspace editing, and sub-agent delegation, over the agent tool runtime, with pluggable stores. Part of the @orkestrel line.",
 	"keywords": [
 		"agent",
@@ -18,14 +18,13 @@
 		"url": "git+https://github.com/orkestrel/tool.git"
 	},
 	"files": [
-		"dist",
+		"dist/src",
 		"README.md"
 	],
 	"type": "module",
 	"sideEffects": false,
 	"main": "./dist/src/core/index.cjs",
 	"module": "./dist/src/core/index.js",
-	"types": "./dist/src/core/index.d.ts",
 	"exports": {
 		".": {
 			"import": {
@@ -53,21 +52,22 @@
 		"access": "public"
 	},
 	"scripts": {
-		"clean": "node -e \"try{require('node:fs').rmSync('dist',{recursive:true,force:true})}catch{}\"",
+		"clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
 		"copy": "node -e \"const fs=require('node:fs'),p=require('node:path'),a=process.argv[1],b=process.argv[2];fs.mkdirSync(p.dirname(b),{recursive:true});fs.cpSync(a,b,{force:true});console.log('Copied: '+a+' to '+b)\"",
-		"tmp:txt": "node -e \"const fs=require('node:fs'),p=require('node:path');function walk(d){for(const e of fs.readdirSync(d,{withFileTypes:true})){const f=p.join(d,e.name);if(e.isDirectory()){walk(f)}else if(!e.name.endsWith('.md')&&!e.name.endsWith('.txt')){const t=f+'.txt';if(!fs.existsSync(t)){fs.renameSync(f,t)}else{console.warn('Skipping '+f+' — target exists: '+t)}}}}try{walk('tmp')}catch(e){if(e.code!=='ENOENT')throw e}\"",
-		"lint": "oxlint --config .oxlintrc.json --fix .",
+		"scaffold": "scaffold",
+		"lint": "oxlint --config .oxlintrc.json --fix --deny-warnings .",
 		"check": "tsc --noEmit --project tsconfig.json && npm run check:src",
 		"check:src": "npm run check:src:core && npm run check:src:server",
 		"check:src:core": "tsc --noEmit -p configs/src/tsconfig.core.json",
 		"check:src:server": "tsc --noEmit -p configs/src/tsconfig.server.json",
 		"format": "oxfmt --config .oxfmtrc.json --write .",
 		"format:check": "oxfmt --config .oxfmtrc.json --check .",
-		"lint:check": "oxlint --config .oxlintrc.json .",
-		"test": "npm run test:src && npm run test:guides",
+		"lint:check": "oxlint --config .oxlintrc.json --deny-warnings .",
+		"test": "npm run test:src && npm run test:policy && npm run test:guides",
 		"test:src": "vitest run --config vite.config.ts --no-cache --reporter=dot --project src:core --project src:server",
 		"test:src:core": "vitest run --config vite.config.ts --no-cache --reporter=dot --project src:core",
 		"test:src:server": "vitest run --config vite.config.ts --no-cache --reporter=dot --project src:server",
+		"test:policy": "vitest run --config vite.config.ts --no-cache --reporter=dot --project policy",
 		"test:guides": "vitest run --config vite.config.ts --reporter=dot --project guides",
 		"build": "npm run clean && npm run build:src",
 		"build:src": "npm run build:src:core && npm run build:src:server",
@@ -76,26 +76,28 @@
 		"prepublishOnly": "npm run format:check && npm run lint:check && npm run check && npm run build && npm test"
 	},
 	"dependencies": {
-		"@orkestrel/agent": "^0.0.7",
-		"@orkestrel/contract": "^0.0.5",
-		"@orkestrel/database": "^0.0.5",
-		"@orkestrel/relation": "^0.0.3",
-		"@orkestrel/server": "^0.0.6",
-		"@orkestrel/terminal": "^0.0.4",
-		"@orkestrel/workflow": "^0.0.6"
+		"@orkestrel/agent": "^0.0.9",
+		"@orkestrel/contract": "^0.0.8",
+		"@orkestrel/database": "^0.0.6",
+		"@orkestrel/relation": "^0.0.6",
+		"@orkestrel/server": "^0.0.7",
+		"@orkestrel/terminal": "^0.0.5",
+		"@orkestrel/workflow": "^0.0.7"
 	},
 	"devDependencies": {
-		"@microsoft/api-extractor": "^7.58.11",
-		"@orkestrel/guide": "^0.0.5",
-		"@types/node": "^26.1.1",
-		"oxfmt": "^0.59.0",
-		"oxlint": "^1.74.0",
+		"@microsoft/api-extractor": "^7.58.12",
+		"@orkestrel/guide": "^0.0.7",
+		"@orkestrel/scaffold": "^0.0.7",
+		"@types/node": "^26.1.2",
+		"@vitest/browser-playwright": "^4.1.10",
+		"oxfmt": "^0.61.0",
+		"oxlint": "^1.76.0",
 		"typescript": "^6.0.3",
 		"vite": "^8.1.5",
 		"vite-plugin-dts": "^5.0.3",
 		"vitest": "^4.1.10"
 	},
 	"engines": {
-		"node": ">=22"
+		"node": ">=22.12.0"
 	}
 }

package/dist/src/server/constants.d.ts

@@ -1,12 +0,0 @@
-/**
- * The default `:name`-templated path {@link import('./factories.js').createTerminalRoutes}
- * mounts its GET (SSE) + POST (answer) routes under.
- */
-export declare const TERMINAL_ROUTES_PATH = "/terminals/:name";
-/**
- * The default SSE keepalive interval (in milliseconds)
- * {@link import('./factories.js').createTerminalRoutes} arms per open connection — a `: `
- * comment ping a conforming SSE parser ignores, keeping intermediary proxies from timing out an
- * otherwise-idle stream.
- */
-export declare const TERMINAL_KEEPALIVE_MS = 15000;

package/dist/src/server/factories.d.ts

@@ -1,44 +0,0 @@
-import { TerminalManagerInterface } from '@orkestrel/terminal';
-import { TerminalRoute, TerminalRoutesOptions } from './types.js';
-/**
- * Build the two `TerminalManagerInterface` (`@orkestrel/terminal`) routes — a GET SSE stream and
- * a POST answer endpoint, both mounted on the SAME `:name`-templated path — that bridge a manager's
- * endpoints onto the wire, byte-compatible with `PromptClient`.
- *
- * @remarks
- * - **GET (SSE).** Optionally token-gated (`401` on mismatch), `404` when `name` names no
- *   endpoint. Opens a stream, replays every currently-{@link import('@orkestrel/terminal').PendingPrompt}
- *   as a `pending` frame, then live-forwards the manager's own `pending` / `expire` events scoped
- *   to `name`. A `keepalive`-interval `: ` comment ping is armed via the injected `timer` (default
- *   the host `setTimeout`). On the request's `AbortSignal` firing (client disconnect OR server
- *   stop) the keepalive is cancelled, both listeners unsubscribed, and the stream ended — no
- *   `shutdown` frame is sent, so a reconnecting client is never told the endpoint is gone.
- * - **POST (answer).** Same token + `404` checks, then reads the body capped at `options.limit`
- *   bytes (`413` over, `manager.answer` never called — see {@link TerminalRoutesOptions.limit}),
- *   parses the JSON body (`400` on invalid JSON, `422` when it isn't an `{ id, value }`
- *   {@link import('@orkestrel/terminal').isAnswerPayload} shape), and routes it through
- *   `manager.answer` — `204` on success, `404` for `'terminal'`, `422` for `'unknown'` / `'rejected'`.
- *
- * @remarks
- * The `token` option (a string OR a validator function — {@link TerminalToken}) is validated at
- * GET connect, on EVERY POST, and RE-VALIDATED on every keepalive tick of a live SSE stream — a
- * stream whose presented token stops validating is torn down rather than left streaming forever.
- * Concurrent POST answerers race first-write-wins — a late POST for an already-settled prompt
- * returns `422`.
- *
- * @param manager - The `TerminalManagerInterface` (`@orkestrel/terminal`) whose endpoints are bridged
- * @param options - See {@link TerminalRoutesOptions}
- * @returns Exactly two {@link TerminalRoute} records — GET then POST — sharing one path
- *
- * @example
- * ```ts
- * import { createTerminalRoutes } from '@src/server'
- * import { createTerminalManager } from '@orkestrel/terminal'
- *
- * const manager = createTerminalManager()
- * manager.add('assistant')
- * const routes = createTerminalRoutes(manager, { token: 'secret' })
- * // mount `routes` against any router accepting `{ method, path, handler }`
- * ```
- */
-export declare function createTerminalRoutes(manager: TerminalManagerInterface, options?: TerminalRoutesOptions): readonly TerminalRoute[];

package/dist/src/server/types.d.ts

@@ -1,60 +0,0 @@
-import { TimerHandler } from '@orkestrel/terminal';
-/** The HTTP method literal a {@link TerminalRoute} declares — the exact 7-literal union `@orkestrel/router`'s `Method` accepts. */
-export type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
-/**
- * The minimal route-dispatch context a {@link TerminalRoute} handler reads — exactly the frozen,
- * URL-decoded `:name` path param slice a router hands a matched handler.
- */
-export interface TerminalRouteContext {
-    readonly params: Readonly<Record<string, string>>;
-}
-/**
- * One structural route record {@link import('./factories.js').createTerminalRoutes} returns — a
- * plain `{ method, path, handler }` shape carrying NO dependency on `@orkestrel/router`'s own
- * `Route` type, so a consumer mounts it against any router that accepts a two-arg
- * `(request, context) => Response | Promise<Response>` handler keyed by `method` + `path`.
- */
-export interface TerminalRoute {
-    readonly method: Method;
-    readonly path: string;
-    readonly handler: (request: Request, context: TerminalRouteContext) => Response | Promise<Response>;
-}
-/**
- * The `token` gate a {@link TerminalRoutesOptions} may configure — a plain string compared for
- * equality against the `x-orkestrel-token` header, OR a validator function the consumer fully
- * controls, enabling expiry/rotation (a JWT `exp` check, a revocation-list lookup, anything
- * time-varying) that a fixed string cannot express. `undefined` disables the auth check entirely.
- */
-export type TerminalToken = string | ((value: string | undefined) => boolean);
-/**
- * Options for {@link import('./factories.js').createTerminalRoutes}.
- *
- * @remarks
- * - `path` — the shared `:name`-templated path both the GET (SSE) and POST (answer) routes
- *   mount under; defaults to {@link import('./constants.js').TERMINAL_ROUTES_PATH}.
- * - `token` — a {@link TerminalToken}: a string is compared for equality against the
- *   `x-orkestrel-token` header; a function receives the header's value (`undefined` when absent)
- *   and returns whether it validates, letting the consumer roll/expire tokens out-of-band.
- *   Validated at GET connect, on EVERY POST, and RE-VALIDATED on every keepalive tick of a live
- *   SSE stream — a stream whose presented token stops validating (rotated, expired, revoked) is
- *   torn down (the abort/self-heal teardown path, no `shutdown` frame) rather than left open
- *   forever; the client reconnects and re-authenticates. Omitted ⇒ no auth check. Because
- *   re-validation only happens on the keepalive tick, the revocation window equals the keepalive
- *   interval — a token rejected/expired between ticks keeps streaming until the next one. A
- *   validator function that THROWS is treated as rejection (fail-closed) at every call site.
- * - `keepalive` — the SSE comment-ping interval in milliseconds; defaults to
- *   {@link import('./constants.js').TERMINAL_KEEPALIVE_MS}.
- * - `timer` — the injected {@link TimerHandler} driving the keepalive interval (default the host
- *   `setTimeout`/`clearTimeout`), so a test drives the keepalive deterministically.
- * - `limit` — the maximum POST answer body size in bytes, streamed and enforced BEFORE JSON
- *   parsing (ignoring any `Content-Length` header, so a lying header can never bypass the cap);
- *   a body exceeding it is rejected `413` and `manager.answer` is never called. Defaults to
- *   `@orkestrel/server`'s own `DEFAULT_BODY_LIMIT` (1 MiB).
- */
-export interface TerminalRoutesOptions {
-    readonly path?: string;
-    readonly token?: TerminalToken;
-    readonly keepalive?: number;
-    readonly timer?: TimerHandler;
-    readonly limit?: number;
-}