@workerdeck/server 0.6.0 → 0.9.0

package/README.md

@@ -39,7 +39,8 @@ import { createWorkerServer } from '@workerdeck/server'
 
 const worker = createWorkerServer({
   authenticate: async (req) => verifyMyAppToken(req.headers.authorization),
-  allowedCwdRoots: ['/srv/checkouts'],          // clamp where sessions may run
+  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
 })
@@ -57,6 +58,9 @@ Routes (default `basePath: '/v1'`):
 | `POST /v1/sessions/:id/permissions/:requestId` | Resolve a pending approval over REST |
 | `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 |
 | `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) |

package/build/index.d.mts

@@ -1,7 +1,7 @@
 import { IncomingMessage, Server, ServerResponse } from "node:http";
-import { BridgeAnswer, BrowserBridgeExecutor, ClaudeAuthProbe, ParkedExecution, Runner, RunnerSnapshot, SessionRunnerConfig, ToolExecutionResult } from "@workerdeck/core";
+import { AttachmentInput, BridgeAnswer, BrowserBridgeExecutor, ClaudeAuthProbe, EngineAdapter, ParkedExecution, Runner, RunnerSnapshot, SessionRunnerConfig, ToolExecutionResult } from "@workerdeck/core";
 import { JobQueue, QueueAdapter } from "@workerdeck/queue";
-import { CreateSessionRequest, JobEvent, ProfileInfo, SdkSessionSummary, ServerFrame, SessionInfo, SessionNotification, SessionWebhookConfig } from "@workerdeck/protocol";
+import { CreateSessionRequest, JobEvent, MessageAttachment, ProfileEngine, ProfileInfo, SdkSessionSummary, ServerFrame, SessionInfo, SessionNotification, SessionWebhookConfig } from "@workerdeck/protocol";
 
 //#region src/registry.d.ts
 type SessionRegistryOptions = {
@@ -327,6 +327,62 @@ type WorkerServerOptions = {
   /** Required unless `allowUnauthenticated: true` — the worker must never be exposed bare. */authenticate?: Authenticator; /** Explicit opt-in to run without auth (local dev only). */
   allowUnauthenticated?: boolean; /** If set, session cwd must resolve inside one of these roots. Strongly recommended. */
   allowedCwdRoots?: string[];
+  /**
+   * The host filesystem routes (`{basePath}/fs/*`) — browse and read the
+   * operator's real project tree, and optionally write to it.
+   *
+   * **Reading follows {@link allowedCwdRoots} and needs no grant of its own.**
+   * A caller holding the auth key can already start a session in any allowed root
+   * and have the agent read whatever is in it, so serving those same trees over
+   * `/fs` adds no authority — it only removes the absurdity of going through a
+   * language model to `cat` a file. Set `roots` here only to *narrow* that (or to
+   * expose a tree sessions may not run in).
+   *
+   * With neither set the routes 404. That is not the same as inheriting
+   * `allowedCwdRoots`' permissive "unset means anywhere": no cwd policy means
+   * there is nothing to inherit, and "anywhere" is a statement about paths the
+   * operator types at a keyboard, not one about what a phone may read.
+   *
+   * **Writing is a separate opt-in**, because it is the one part that is not
+   * already implied. An agent's writes go through the permission flow; a `PUT` to
+   * `/fs/write` does not. These routes are operator-privileged by design — the
+   * caller is the operator — but that is a reason to make the bypass deliberate,
+   * not a reason to skip the switch.
+   *
+   * Containment is *not* `cwdAllowed`, whichever roots are in play: these routes
+   * walk paths the agent may have authored, so a symlink can escape a lexical
+   * prefix check. See `host-files.ts` — canonicalize, then re-check.
+   */
+  hostFiles?: {
+    /** Absolute paths. Unset inherits {@link allowedCwdRoots}; an explicit empty
+     * array disables the routes (a policy, not an absence). */
+    roots?: string[]; /** Enable `PUT {basePath}/fs/write`. Default false — read-only. */
+    write?: boolean;
+    /** Refuse reads above this (413) rather than streaming a gigabyte to a phone.
+     * Default 1 MiB. Writes are bounded by {@link maxBodyBytes} instead. */
+    maxFileBytes?: number;
+    /** Cap on entries returned per directory (the response says `truncated`).
+     * Default 5000. */
+    maxEntries?: number;
+    /** Directory names `GET /fs/find` will not descend into. Defaults to
+     * `DEFAULT_IGNORED_DIRS` (`.git`, `node_modules`, build output…) — the thing
+     * that keeps a per-keystroke search cheap on a real source tree. */
+    ignore?: string[];
+  };
+  /**
+   * Message attachments (`{basePath}/sessions/:id/attachments`) — the photos and
+   * files a client sends alongside a message. Always on; these knobs only size it.
+   *
+   * There is no grant to make here the way `hostFiles.write` is one: an upload
+   * lands in the session's own in-memory hold and reaches the model as message
+   * content, which is exactly what typing does. What it *can* do is cost memory,
+   * so both caps default low enough that a phone camera roll cannot fill the
+   * gateway.
+   */
+  attachments?: {
+    /** Largest single upload; over it is a 413. Default 10 MiB. */maxFileBytes?: number; /** Ceiling on what one session holds at once. Default 64 MiB. */
+    maxSessionBytes?: number;
+  };
   /**
    * Named Claude Code config directories sessions can run under (each becomes the
    * session's CLAUDE_CONFIG_DIR — settings, memory, skills, and the credentials the
@@ -413,8 +469,11 @@ type WorkerServerOptions = {
     probe?: ClaudeAuthProbe;
     timeoutMs?: number;
   };
-  /** Injectable lister for GET /sdk-sessions (tests). Defaults to the SDK's listSessions,
-   * which reads the Agent SDK's on-disk session store. */
+  /** Injectable lister for GET /sdk-sessions (tests) — honored for the CLAUDE
+   * engine only, like the injectable claude auth probe (it predates the adapter
+   * layer). Defaults to the claude adapter's lister (the SDK's on-disk session
+   * store); other engines always answer through their adapter's
+   * `listSessions`. */
   listSdkSessions?: SdkSessionLister;
   /** Enable the job queue (`/jobs` + `/queue` routes). Jobs run as ordinary registry
    * sessions — attachable over the sessions WS — governed by these limits. */
@@ -467,6 +526,8 @@ type WorkerServerOptions = {
    * Kept as a host hook so the server package neither imports a model SDK nor
    * decides how provider credentials are resolved: the factory reads them from
    * the operator's environment, exactly like the Claude credential chain.
+   * `claude` and `codex` profiles never come through here — those engines ship
+   * as in-repo adapters (`@workerdeck/core`'s `getEngineAdapter`).
    *
    * May be async: assembly that has to await — a per-session MCP connect, a
    * credential lookup — belongs here, with `AiSdkRunnerConfig.onClose` as the
@@ -474,6 +535,13 @@ type WorkerServerOptions = {
    * the message, a job goes straight to `failed`.
    */
   createEngineRunner?: (context: EngineRunnerContext) => Runner | Promise<Runner>;
+  /**
+   * Adapter overrides, keyed by engine — **for tests only** (the server
+   * integration suite injects a fake codex engine so `pnpm test` spawns no
+   * binary). Not a public extension point: third engines belong in core as
+   * adapters, or behind `createEngineRunner` as provider profiles.
+   */
+  engines?: Partial<Record<ProfileEngine, EngineAdapter>>;
 };
 type EngineRunnerContext = {
   /** The session config, with profile defaults already applied. */config: SessionRunnerConfig; /** The profile that selected this engine. */
@@ -526,5 +594,69 @@ type WorkerServer = {
 };
 declare function createWorkerServer(options?: WorkerServerOptions): WorkerServer;
 //#endregion
-export { type Authenticator, BridgeHub, type BridgeHubOptions, type EngineRunnerContext, type FileSessionStoreOptions, MemorySessionStore, type ParkedSessionRecord, type ProfileStore, type QueueServerOptions, type SdkSessionLister, type SessionNotificationOptions, SessionNotifier, SessionParkManager, type SessionParkOptions, SessionRegistry, type SessionRegistryOptions, type SessionStore, type WorkerServer, type WorkerServerOptions, createFileProfileStore, createFileSessionStore, createMemoryProfileStore, createWorkerServer, toDurableRecord };
+//#region src/attachments.d.ts
+type AttachmentStoreOptions = {
+  /** Largest single upload. Default 10 MiB. */maxFileBytes?: number; /** Ceiling on everything one session is holding. Default 64 MiB. */
+  maxSessionBytes?: number;
+};
+type AttachmentRejection = {
+  code: 'too_large';
+  message: string;
+} | {
+  code: 'session_full';
+  message: string;
+} | {
+  code: 'unsupported_type';
+  message: string;
+} | {
+  code: 'empty';
+  message: string;
+};
+type PutResult = {
+  ok: true;
+  attachment: MessageAttachment;
+} | {
+  ok: false;
+  error: AttachmentRejection;
+};
+/**
+ * Per-session hold for files the user attached to a message.
+ *
+ * In memory, and deliberately so. An attachment is only *needed* for the instant
+ * between the upload and the message that names it; everything after that is
+ * convenience (a client re-rendering a thumbnail after a reattach). That is the
+ * same bargain `GET /sessions/:id/files` makes — the session's lifetime, no
+ * durability tier — and it keeps the gateway from accumulating a photo library
+ * on disk that nobody asked it to look after.
+ *
+ * Both caps are enforced here rather than at the route, so a host embedding the
+ * server cannot forget one: a single file that is too big is a 413, and so is a
+ * session whose total would go over.
+ */
+declare class AttachmentStore {
+  #private;
+  constructor(options?: AttachmentStoreOptions);
+  get maxFileBytes(): number;
+  put(sessionId: string, name: string, mediaType: string, body: Buffer): PutResult;
+  /** The stored record, bytes included — for the download route and for the send
+   * path that turns ids into content blocks. */
+  get(sessionId: string, id: string): AttachmentInput | undefined;
+  /**
+   * Resolve the ids a `user_message` named, in the order given.
+   *
+   * Missing ids are reported rather than skipped: a message that quietly lost its
+   * picture reads as the model ignoring it, which is a far worse failure than a
+   * command that errors.
+   */
+  resolve(sessionId: string, ids: readonly string[]): {
+    ok: true;
+    attachments: AttachmentInput[];
+  } | {
+    ok: false;
+    missing: string[];
+  };
+  drop(sessionId: string): void;
+}
+//#endregion
+export { AttachmentStore, type AttachmentStoreOptions, type Authenticator, BridgeHub, type BridgeHubOptions, type EngineRunnerContext, type FileSessionStoreOptions, MemorySessionStore, type ParkedSessionRecord, type ProfileStore, type QueueServerOptions, type SdkSessionLister, type SessionNotificationOptions, SessionNotifier, SessionParkManager, type SessionParkOptions, SessionRegistry, type SessionRegistryOptions, type SessionStore, type WorkerServer, type WorkerServerOptions, createFileProfileStore, createFileSessionStore, createMemoryProfileStore, createWorkerServer, toDurableRecord };
 //# sourceMappingURL=index.d.mts.map