@workerdeck/server 2.7.1 → 2.8.0

package/README.md

@@ -3,7 +3,7 @@
 The WorkerDeck gateway: HTTP + WebSocket session server over
 [`@workerdeck/core`](https://www.npmjs.com/package/@workerdeck/core). Session registry
 (create/list/attach/interrupt/kill), pluggable auth hook, replay-from-seq attach, profiles,
-parked-session storage, optional job-queue routes. Runs anywhere Node runs — needs a real
+parked-session storage, optional job-queue routes. Runs anywhere Node runs - needs a real
 filesystem (no serverless).
 
 Want the whole thing running rather than embedded? [`workerdeck`](https://www.npmjs.com/package/workerdeck)
@@ -24,22 +24,22 @@ npm install @workerdeck/server
 ```
 
 Node ≥ 22. The Agent SDK spawns the Claude Code CLI as a long-running subprocess with filesystem
-state — edge/serverless functions cannot host this; realistic targets are a VM or a container.
+state - edge/serverless functions cannot host this; realistic targets are a VM or a container.
 The server implements no Anthropic auth: the SDK/CLI resolves credentials from the operator's
 environment (`ANTHROPIC_API_KEY`, Bedrock/Vertex, or a personal `claude login`).
 
 ## Usage
 
-The host app supplies the authenticator — return a truthy principal to accept, null/undefined to
+The host app supplies the authenticator - return a truthy principal to accept, null/undefined to
 reject with 401. `createWorkerServer` refuses to start without `authenticate` unless you
-explicitly pass `allowUnauthenticated: true` (loopback dev only — never expose that):
+explicitly pass `allowUnauthenticated: true` (loopback dev only - never expose that):
 
 ```ts
 import { createWorkerServer } from '@workerdeck/server'
 
 const worker = createWorkerServer({
   authenticate: async (req) => verifyMyAppToken(req.headers.authorization),
-  allowedCwdRoots: ['/srv/checkouts'],          // where sessions may run — and what /fs serves
+  allowedCwdRoots: ['/srv/checkouts'],          // where sessions may run - and what /fs serves
   hostFiles: { write: true },                   // /fs reads follow the roots above; writing opts in
   buildRunnerConfig: (req) => ({ ...req, env: { ...process.env } }),
   requireApiKey: true,                          // fail closed on subscription credentials
@@ -60,22 +60,22 @@ Routes (default `basePath: '/v1'`):
 | `GET /v1/sdk-sessions?dir=…` | List the Agent SDK's on-disk sessions to offer resume |
 | `GET /v1/sessions/:id/files`, `…/files/<path>` | List and download a session's scratch-filesystem deliverables |
 | `GET /v1/fs/roots`, `/fs/list?path=`, `/fs/read?path=` | Browse and read the **host's** real tree (the `allowedCwdRoots` trees, unless `hostFiles.roots` narrows them; 404 when neither is set) |
-| `GET /v1/fs/find?path=&q=` | Recursive fuzzy file search under one directory — what backs `@file` completion |
-| `PUT /v1/fs/write` | Save a host file — needs `hostFiles.write`, and always carries the hash it replaces |
+| `GET /v1/fs/find?path=&q=` | Recursive fuzzy file search under one directory - what backs `@file` completion |
+| `PUT /v1/fs/write` | Save a host file - needs `hostFiles.write`, and always carries the hash it replaces |
 | `POST /v1/executions/:executionId/result` | Deliver a deferred execution's result, waking a parked session |
 | `GET /v1/profiles`, `GET /v1/profiles/:name` | What sessions may run as (+ a view-only config snapshot) |
 | `GET/POST /v1/jobs`, `GET/DELETE /v1/jobs/:id` | Job queue (when `queue` is configured) |
 | `GET /v1/queue`, `WS /v1/queue/ws` | Queue stats / one-way live stream of job events + stats |
 
-Requests outside `basePath` fall through to the optional `fallback` hook — which is how the
+Requests outside `basePath` fall through to the optional `fallback` hook - which is how the
 turnkey instance serves a dashboard from the same origin, so a browser's WebSocket attach can
 present a cookie.
 
 ## Profiles and the second engine
 
 A **profile** is what a session runs as, and which engine runs it. Declared at startup (or managed
-over the API with a `profileStore`), each one names either a Claude Code config directory — applied
-as that session's `CLAUDE_CONFIG_DIR` — or a model provider for the model-agnostic engine:
+over the API with a `profileStore`), each one names either a Claude Code config directory - applied
+as that session's `CLAUDE_CONFIG_DIR` - or a model provider for the model-agnostic engine:
 
 ```ts
 createWorkerServer({
@@ -88,19 +88,19 @@ createWorkerServer({
     {
       name: 'kimi',
       engine: 'provider',
-      // A variable NAME — no credential is stored here or served by GET /profiles.
+      // A variable NAME - no credential is stored here or served by GET /profiles.
       provider: { id: 'moonshotai', model: 'kimi-k3', apiKeyEnv: 'MOONSHOT_API_KEY' },
       session: { capabilities: ['web_fetch', 'deliver_file'] },
     },
   ],
-  // The one place a model SDK and its credentials are resolved — this package imports neither.
+  // The one place a model SDK and its credentials are resolved - this package imports neither.
   createEngineRunner: ({ config, profile, bridge }) => buildProviderRunner({ /* … */ }),
 })
 ```
 
 With more than one profile declared, every create must name its `profile`; with exactly one it is
 implicit, and with the option unset a `default` is auto-detected from `~/.claude`.
-`allowedProfiles` on the principal scopes who may run as what — the line between one worker serving
+`allowedProfiles` on the principal scopes who may run as what - the line between one worker serving
 several people and account pooling. `SessionInfo.engine` and `supportsPermissionMode` let a UI hide
 affordances the provider engine doesn't have; asking for one anyway is a 400 rather than a silent
 coercion.
@@ -108,7 +108,7 @@ coercion.
 ## Parked sessions
 
 A session whose tool call can't answer in the next few seconds **parks**: the runner is torn down,
-its snapshot goes to a `SessionStore`, and `POST /executions/:id/result` rebuilds it — same id,
+its snapshot goes to a `SessionStore`, and `POST /executions/:id/result` rebuilds it - same id,
 same event log, same seq numbering, mid-turn. Results are idempotent by `executionId`. The default
 store is in-memory (a park survives a client disconnect, not a restart); the bundled file store
 survives both, on one host:
@@ -123,12 +123,12 @@ createWorkerServer({
 })
 ```
 
-That directory holds each parked session's whole transcript in plaintext — protect it like the
+That directory holds each parked session's whole transcript in plaintext - protect it like the
 SDK's own `~/.claude/projects`. Credentials never reach it. One process per directory.
 
 ## Job queue
 
-Pass `queue` options to mount the job routes — one-shot unattended runs with bounded concurrency,
+Pass `queue` options to mount the job routes - one-shot unattended runs with bounded concurrency,
 token budgets, retries, and webhook delivery:
 
 ```ts
@@ -145,7 +145,7 @@ const worker = createWorkerServer({
 })
 ```
 
-Job sessions are ordinary registry sessions — attachable over the sessions WS — and go through
+Job sessions are ordinary registry sessions - attachable over the sessions WS - and go through
 the same `buildRunnerConfig` hook and auth-provenance watcher as client sessions. The in-memory
 adapter is single-process and non-persistent; implement `QueueAdapter` against a shared store for
 anything beyond one trusted host.
@@ -153,7 +153,7 @@ anything beyond one trusted host.
 ## Session notifications
 
 The live WebSocket only reaches someone who has one open. `notifications` is the outbound
-channel for everyone else — the four moments a person acts on, POSTed to a URL you control:
+channel for everyone else - the four moments a person acts on, POSTed to a URL you control:
 
 ```ts
 const worker = createWorkerServer({
@@ -166,13 +166,13 @@ const worker = createWorkerServer({
 })
 ```
 
-`permission_requested`, `turn_completed`, `session_error`, `session_closed` — delivered as a
+`permission_requested`, `turn_completed`, `session_error`, `session_closed` - delivered as a
 `SessionNotification`, ordered per session, retried with exponential backoff. Server-wide, unlike
 the queue's per-job `webhook`: the point is hearing about sessions you neither created nor are
 attached to, and every registry session qualifies (job runs and rebuilt parked sessions included).
 
 `permission_requested` carries the whole `PermissionRequest`, so a consumer can answer it with
-`POST /sessions/:id/permissions/:requestId` — the mechanism behind an Approve button in a chat
+`POST /sessions/:id/permissions/:requestId` - the mechanism behind an Approve button in a chat
 message or on a phone's lock screen. The server holds no push credentials and knows nothing about
 APNs, FCM or Slack; forwarding to one of those is a separate process's job.
 
@@ -180,10 +180,10 @@ APNs, FCM or Slack; forwarding to one of those is a separate process's job.
 
 Each session's credential provenance surfaces as `apiKeySource` on `SessionInfo` and the
 `system_init` event; `'oauth'` means claude.ai subscription credentials. With
-`requireApiKey: true` such sessions are terminated with a `session_error` — recommended for
+`requireApiKey: true` such sessions are terminated with a `session_error` - recommended for
 services and any unattended use. Without it the server logs a one-time notice instead
 (appropriate only for personal single-user deployments). WorkerDeck never implements claude.ai
-OAuth, never reads or forwards tokens — see the repo README's
+OAuth, never reads or forwards tokens - see the repo README's
 ["Auth & Anthropic's terms"](https://github.com/workerdeck/workerdeck#auth--anthropics-terms).
 
 ## Rules you cannot infer from the types
@@ -192,7 +192,7 @@ OAuth, never reads or forwards tokens — see the repo README's
   caller's business, so the out-of-scope answer is byte-identical to the unknown-id one.
 - **Visibility is full control.** There is no read-only attach: a client that can see a session can
   send `user_message`, `permission_decision`, `interrupt` and `close`. `SessionPanel`'s `readOnly`
-  removes the affordance, not the authority — enforce at the gateway or not at all.
+  removes the affordance, not the authority - enforce at the gateway or not at all.
 - **`authorizeSession` is synchronous on purpose.** It runs per route and per row of every list. An
   expensive lookup belongs in `authenticate`, where it happens once and lands on the principal.
 - **`sandboxedProviderProfile()`'s empty arrays are load-bearing.** `capabilities: []` and
@@ -202,15 +202,15 @@ OAuth, never reads or forwards tokens — see the repo README's
   variable at all moves the CLI off the macOS Keychain, so pinning the default directory breaks a
   working `claude login`. "Pin the default dir" and "don't pin" are different logins.
 - **`checkCredentials` is display-only** unless you also set `requireAvailableProfile`. A create
-  against an unavailable profile otherwise proceeds and fails with the engine's own error — right
+  against an unavailable profile otherwise proceeds and fails with the engine's own error - right
   for an operator (the probe can be stale), wrong in front of an end user.
 - **`createEngineRunner` has four invisible obligations**: forward `restore`, adopt `id`, seed the
   VFS only when *not* restoring, and dispose per-session resources via `onClose`. Every one is a
   runtime-only failure. `createProviderRunner()` does all four; reach for the raw hook only when it
   genuinely doesn't fit.
 - **`parking.persistLive` is how a *provider* session survives a restart, and it needs a durable
-  store to mean anything.** Claude and codex go dormant — remembered by engine session id and
-  resumed from the engine's own store — which a provider session cannot do, so its record carries
+  store to mean anything.** Claude and codex go dormant - remembered by engine session id and
+  resumed from the engine's own store - which a provider session cannot do, so its record carries
   the state itself, written through after every turn. With the default in-memory store the option
   does nothing and says nothing. It is off by default: a library must not start writing sessions'
   transcripts to disk because someone upgraded, and the record holds the whole transcript in
@@ -220,9 +220,9 @@ OAuth, never reads or forwards tokens — see the repo README's
   implement a `SessionStore`, do not "tidy up" a record on read.
 - **One origin is not a convenience.** A browser cannot put an `Authorization` header on a
   WebSocket upgrade, so a cookie is the only credential a tab can present on an attach, and a
-  cookie is per-origin. That is what `fallback` is for — an app served from the gateway's own port.
+  cookie is per-origin. That is what `fallback` is for - an app served from the gateway's own port.
 
 ## License
 
-MIT © Tobias Strebitzer —
+MIT © Tobias Strebitzer -
 [LICENSE](https://github.com/workerdeck/workerdeck/blob/master/LICENSE)

package/build/index.mjs

@@ -712,7 +712,7 @@ async function handleHostFiles(ctx, req, res, pathname) {
 		}
 		const existing = current.ok ? current.data : null;
 		if (existing && !body.expectedHash) {
-			json(res, 409, { error: "file exists — pass expectedHash to overwrite it" });
+			json(res, 409, { error: "file exists - pass expectedHash to overwrite it" });
 			return;
 		}
 		if (existing && hashBytes(existing) !== body.expectedHash) {
@@ -1068,7 +1068,7 @@ function createFileSessionStore(options = {}) {
 					path,
 					op: "save"
 				});
-				throw new Error(`parked session '${record.id}' is not JSON-serializable — a host-injected value reached its config or snapshot: ${String(error)}`, { cause: error });
+				throw new Error(`parked session '${record.id}' is not JSON-serializable - a host-injected value reached its config or snapshot: ${String(error)}`, { cause: error });
 			}
 			try {
 				await mkdir(dir, {
@@ -2574,7 +2574,7 @@ var SessionParkManager = class {
 		}
 		if (runner.id !== id) {
 			runner.close("error");
-			const error = /* @__PURE__ */ new Error(`rebuilt session has id '${runner.id}', expected '${id}' — the engine factory must forward EngineRunnerContext.restore (or, without a snapshot, the session id) to the runner config`);
+			const error = /* @__PURE__ */ new Error(`rebuilt session has id '${runner.id}', expected '${id}' - the engine factory must forward EngineRunnerContext.restore (or, without a snapshot, the session id) to the runner config`);
 			this.#options.onError?.(error, {
 				sessionId: id,
 				phase: "resume"
@@ -2682,7 +2682,7 @@ var ProfileService = class {
 			if (!hasEngineRunnerFactory) return `profile '${p.name}' uses engine 'provider' but no \`createEngineRunner\` was provided to build one`;
 		} else if (p.engine === "codex") {
 			if (p.codexHome && !existsSync(p.codexHome)) return `profile '${p.name}' codexHome does not exist: ${p.codexHome}`;
-			if (p.session?.instructions) return `profile '${p.name}' declares session.instructions, which the codex engine cannot deliver — put instructions in the target repo’s AGENTS.md instead`;
+			if (p.session?.instructions) return `profile '${p.name}' declares session.instructions, which the codex engine cannot deliver - put instructions in the target repo’s AGENTS.md instead`;
 		} else if (!p.configDir || !existsSync(p.configDir)) return `profile '${p.name}' configDir does not exist: ${p.configDir}`;
 		if (disableBypassPermissions && p.defaults?.permissionMode === "bypassPermissions") return `profile '${p.name}' defaults to bypassPermissions but disableBypassPermissions is set`;
 		const fallbackMode = p.defaults?.permissionMode;
@@ -2745,7 +2745,7 @@ var ProfileService = class {
 	declaredGuard(profile) {
 		return this.#declaredByName.has(profile.name) ? {
 			status: 403,
-			error: `profile '${profile.name}' is declared in server options and cannot be changed over the API — edit the \`profiles\` option instead`
+			error: `profile '${profile.name}' is declared in server options and cannot be changed over the API - edit the \`profiles\` option instead`
 		} : null;
 	}
 	configDirGuard(profile) {
@@ -2895,13 +2895,13 @@ function createSessionFactory(deps) {
 	};
 	const checkPermissionMode = (mode, profile) => {
 		if (mode === void 0 || supportsPermissionMode(profile?.engine, mode)) return null;
-		return `permission mode '${mode}' is not supported by profile '${profile.name}' (engine '${engineOf(profile)}') — supported: ` + adapterFor(profile?.engine).capabilities.permissionModes.join(", ");
+		return `permission mode '${mode}' is not supported by profile '${profile.name}' (engine '${engineOf(profile)}') - supported: ` + adapterFor(profile?.engine).capabilities.permissionModes.join(", ");
 	};
 	const checkEngineGrants = (req, profile) => {
 		const engine = engineOf(profile);
 		const caps = adapterFor(profile?.engine).capabilities;
 		const name = profile?.name ?? "default";
-		if (!caps.sessionMcpServers && req.mcpServers && Object.keys(req.mcpServers).length > 0) return `profile '${name}' runs the ${engine} engine, whose MCP servers are declared outside the session request — a request cannot add its own`;
+		if (!caps.sessionMcpServers && req.mcpServers && Object.keys(req.mcpServers).length > 0) return `profile '${name}' runs the ${engine} engine, whose MCP servers are declared outside the session request - a request cannot add its own`;
 		if (!caps.budgets && (req.maxTurns !== void 0 || req.maxBudgetUsd !== void 0)) return `the ${engine} engine does not honor maxTurns/maxBudgetUsd`;
 		if (!caps.settingSources && req.settingSources !== void 0) return `the ${engine} engine does not load settingSources`;
 		if (!caps.resume && req.resume !== void 0) return `the ${engine} engine cannot resume a session`;
@@ -2912,7 +2912,7 @@ function createSessionFactory(deps) {
 		if (!req.capabilities || !granted) return null;
 		const ungranted = req.capabilities.filter((c) => !granted.includes(c));
 		if (ungranted.length === 0) return null;
-		return `profile '${profile.name}' does not grant: ${ungranted.join(", ")} (granted: ${granted.join(", ") || "none"}) — a request may narrow capabilities, not widen them`;
+		return `profile '${profile.name}' does not grant: ${ungranted.join(", ")} (granted: ${granted.join(", ") || "none"}) - a request may narrow capabilities, not widen them`;
 	};
 	const stripInertFields = (req, profile) => {
 		if (!adapterFor(profile?.engine).capabilities.interactiveApprovals) delete req.questionBehavior;
@@ -3006,7 +3006,7 @@ function createSessionFactory(deps) {
 			id
 		});
 		const reported = runner.info().scope;
-		if (!sameScope(reported, config.scope)) throw new Error(`runner for session ${runner.id} reports scope ${JSON.stringify(reported)}, expected ${JSON.stringify(config.scope)} — echo config.scope from info()`);
+		if (!sameScope(reported, config.scope)) throw new Error(`runner for session ${runner.id} reports scope ${JSON.stringify(reported)}, expected ${JSON.stringify(config.scope)} - echo config.scope from info()`);
 		return runner;
 	};
 	const createRunner = async (config) => {
@@ -3062,7 +3062,7 @@ function createSessionFactory(deps) {
 				if (subscriptionNoticeShown.has(profileName)) return;
 				subscriptionNoticeShown.add(profileName);
 				const scope = profileName ? `Sessions under profile '${profileName}'` : "Sessions";
-				console.warn(`[workerdeck] ${scope} are using claude.ai subscription credentials (apiKeySource 'oauth'), not an API key. That is only appropriate for personal, single-user use of your own account. Unattended/scheduled or multi-user use requires an API key under Anthropic's terms — set ANTHROPIC_API_KEY in the server environment, or set requireApiKey: true to fail closed.`);
+				console.warn(`[workerdeck] ${scope} are using claude.ai subscription credentials (apiKeySource 'oauth'), not an API key. That is only appropriate for personal, single-user use of your own account. Unattended/scheduled or multi-user use requires an API key under Anthropic's terms - set ANTHROPIC_API_KEY in the server environment, or set requireApiKey: true to fail closed.`);
 			}
 		});
 	};