@workerdeck/server 0.7.0 → 0.10.0

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 = {
@@ -369,6 +369,20 @@ type WorkerServerOptions = {
      * 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
@@ -455,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. */
@@ -509,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
@@ -516,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. */
@@ -568,5 +594,119 @@ 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
+//#region src/produced-files.d.ts
+/** One host file an engine reported writing, as the store holds it. */
+type ProducedFile = {
+  fileId: string; /** Absolute host path, exactly as the runner reported it. */
+  path: string;
+  mediaType?: string; /** Size when the runner announced it — advisory, and re-read at serve time. */
+  bytes?: number;
+  sessionId: string;
+};
+/**
+ * The paths this gateway will serve from `GET /sessions/:id/produced/:fileId`.
+ *
+ * **This is the whole access-control model, so it is worth being precise about
+ * what it is.** The store is an allowlist built from one source and one only:
+ * `file_produced` events, which a runner emits about a file its own engine just
+ * wrote. It is not a directory grant. Nothing else can add to it — not a
+ * request, not a config, and in particular not the agent, whose own path claims
+ * go through `/fs/*` and that route's root allowlist.
+ *
+ * That is why the route needs neither `hostFiles.roots` nor `maxFileBytes`:
+ * "somewhere under a root the operator declared" is a guess about which paths
+ * are safe, while "the exact path this session's runner reported producing" is
+ * a fact about one file. A 2 MB generated PNG is the common case, and making
+ * the operator raise a byte cap to see their own picture was the bug this
+ * replaces.
+ *
+ * Lifetime is the session's, like `AttachmentStore`'s: in memory, dropped when
+ * the session is removed. The bytes are never held here — only the path, so a
+ * gateway serving a long session accumulates a few hundred bytes per picture
+ * rather than the pictures.
+ */
+declare class ProducedFileStore {
+  #private;
+  /**
+   * Register a runner's produced files for its lifetime.
+   *
+   * Subscribes from seq 0, which is the opposite of what `SessionNotifier` wants
+   * and correct for the same reason: registration is idempotent (a `fileId` is
+   * derived from its path, so re-registering overwrites with itself), and a
+   * session rebuilt from a park must re-learn every file it produced before the
+   * park — otherwise a client's transcript keeps rendering image cards whose
+   * bytes have quietly become unreachable.
+   */
+  watch(runner: Runner): void;
+  get(sessionId: string, fileId: string): ProducedFile | undefined;
+  /** Everything one session has produced, newest registration last. */
+  list(sessionId: string): ProducedFile[];
+  drop(sessionId: string): void;
+}
+//#endregion
+export { AttachmentStore, type AttachmentStoreOptions, type Authenticator, BridgeHub, type BridgeHubOptions, type EngineRunnerContext, type FileSessionStoreOptions, MemorySessionStore, type ParkedSessionRecord, type ProducedFile, ProducedFileStore, 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