@edspencer/paddock 0.0.1 → 0.56.0

package/packages/server/dist/models.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Models module — the single source of truth for the Claude model ids paddock
+ * exposes (keeper + sweeper defaults, the picker list, and per-model context
+ * limits).
+ *
+ * The wire contract (CONTRACT-v3 §2/§3) and every consumer (the `/api/models`
+ * route, the project `model` resolution in projects.ts, the keeper/sweeper
+ * registration in herdctl.ts, and the context-meter math in ws.ts) read these
+ * constants — so changing the available models or a context limit is a one-file
+ * edit here.
+ *
+ * Context limits (verified against the Models API): Opus 5, Fable 5, Opus 4.8
+ * and Sonnet 5 all have a 1,000,000-token context window; Haiku 4.5 is 200,000.
+ * On the Max plan the keeper agents run Opus 5 at its full 1M window, so
+ * the context meter must use 1M for it — otherwise a long chat reads >100%.
+ */
+/**
+ * Public first-party API list price per 1M tokens, used only to put a
+ * ballpark dollar figure on a chat's cumulative token consumption (issue #152).
+ * On the Max plan the keeper agents don't draw against a per-token
+ * quota, so this is an "at API rates" estimate for comparison, not real spend —
+ * the token counts are the honest metric. Cache-write / cache-read rates are the
+ * standard multiples of the input rate (5-minute ephemeral write = 1.25×, read =
+ * 0.1×), applied in {@link estimateCostUsd}.
+ */
+export interface ModelPricing {
+    /** USD per 1M input tokens. */
+    inputPer1M: number;
+    /** USD per 1M output tokens. */
+    outputPer1M: number;
+}
+/** A single selectable model: its id, a human label, and its context window. */
+export interface ModelInfo {
+    /** The Claude model id passed to herdctl / the SDK (e.g. "claude-opus-4-8"). */
+    id: string;
+    /** Human-friendly label for the picker (e.g. "Opus 4.8"). */
+    label: string;
+    /** Total context window in tokens (used for the context meter). */
+    contextLimit: number;
+    /** First-party list price per 1M tokens, for the cumulative-cost estimate. */
+    pricing?: ModelPricing;
+}
+/**
+ * The selectable models, in picker order. The first entry is the keeper default
+ * (Opus); the cheap Haiku is the sweeper default. Order here is the order the UI
+ * renders.
+ */
+export declare const MODELS: ModelInfo[];
+/** The model a project runs on unless the project overrides it. */
+export declare const DEFAULT_MODEL = "claude-opus-5";
+/**
+ * Resolve the models OFFERED (the picker/allow-list) from an optional list of
+ * allowed ids (issue #457 Step 2). {@link MODELS} stays the authoritative CATALOG
+ * — the source of every model's metadata (label/contextLimit/pricing) and the
+ * validation set for {@link isKnownModel}; this only narrows WHICH catalog models
+ * an instance/project offers.
+ *
+ * - `allowIds` undefined or empty ⇒ every catalog model is offered (today's
+ *   behaviour, fully backward-compatible).
+ * - Otherwise the catalog is filtered to `allowIds`, PRESERVING catalog order and
+ *   metadata (the returned entries are the catalog's own `ModelInfo` objects, so
+ *   an operator can't set a wrong context limit — they only pick by id).
+ * - Unknown ids in `allowIds` are ignored (they aren't in the catalog).
+ *
+ * The result may be empty only when every id was unknown; callers that must never
+ * offer zero models (the config loader) collapse that back to the full catalog.
+ */
+export declare function resolveModels(allowIds?: string[]): ModelInfo[];
+/**
+ * The effective default model for a resolved model list: {@link DEFAULT_MODEL}
+ * when it's still offered, else the first offered model's id (the list is in
+ * picker order, so the first entry is the natural default). Falls back to
+ * {@link DEFAULT_MODEL} when the list is empty, so callers always get a
+ * concrete id.
+ */
+export declare function resolveDefaultModel(models: ModelInfo[]): string;
+/**
+ * Per-project keeper-agent settings surfaced in the project settings UI
+ * (issue #12). These mirror the fleet-wide `defaults` in herdctl.ts so a project
+ * that doesn't override a field inherits the same value it would have anyway —
+ * they're the single source of truth for both the defaults block and the DTO
+ * resolution.
+ */
+/**
+ * The keeper `permission_mode` values offered in the settings UI. A curated
+ * subset of herdctl's PermissionMode enum (default / acceptEdits / plan /
+ * bypassPermissions) — the niche delegate/dontAsk modes are omitted.
+ */
+export declare const PERMISSION_MODES: readonly ["default", "acceptEdits", "plan", "bypassPermissions"];
+export type PermissionMode = (typeof PERMISSION_MODES)[number];
+/** Defaults inherited when a project doesn't override the field. */
+export declare const DEFAULT_PERMISSION_MODE: PermissionMode;
+export declare const DEFAULT_MAX_TURNS = 200;
+export declare const DEFAULT_DOCKER = false;
+/** Upper bound on a project's `max_turns` (guards the UI + PATCH validation). */
+export declare const MAX_TURNS_LIMIT = 1000;
+/**
+ * How a keeper chat turn is driven (Paddock#111):
+ *  - `batch`   — one-shot `FleetManager.trigger()` per turn (the legacy path);
+ *                the `claude` process exits at the turn boundary, so scheduled
+ *                wakeups / background tasks silently die.
+ *  - `session` — a persistent, herdctl-managed `openChatSession` per turn
+ *                (`manageLifecycle: true`); the session is reaped when idle and
+ *                its timer-class wakeups are re-triggered through the scheduler,
+ *                so cross-turn autonomy (`ScheduleWakeup`, `/loop`) actually
+ *                works. See herdctl#307 (reaper) and herdctl#303 (SDK bump).
+ */
+export declare const DRIVE_MODES: readonly ["batch", "session"];
+export type DriveMode = (typeof DRIVE_MODES)[number];
+/**
+ * Default drive mode. `session` (#316): a fresh/un-configured instance
+ * gets cross-turn autonomy (`ScheduleWakeup`, `/loop`, reaper-backed background
+ * work) and the SDK streaming runtime by default, instead of only when an
+ * operator sets `PADDOCK_DRIVE_MODE=session`. The env var and per-project
+ * `driveMode` override still take precedence; this only moves the built-in
+ * default off the legacy one-shot `batch` path.
+ */
+export declare const DEFAULT_DRIVE_MODE: DriveMode;
+/** Whether `m` is one of the offered keeper permission modes. */
+export declare function isKnownPermissionMode(m: string): m is PermissionMode;
+/** Whether `m` is a known keeper drive mode. */
+export declare function isKnownDriveMode(m: string): m is DriveMode;
+/** Whether `n` is a valid keeper `max_turns` (positive integer within bounds). */
+export declare function isValidMaxTurns(n: unknown): n is number;
+/** The cheap model the post-turn sweeper (curator) always uses. */
+export declare const SWEEPER_DEFAULT_MODEL = "claude-haiku-4-5-20251001";
+/** Whether `id` is one of the known selectable models. */
+export declare function isKnownModel(id: string): boolean;
+/**
+ * The context limit (in tokens) for a model id. Falls back to 200000 for an
+ * unknown id so the context meter never divides by an undefined/zero limit.
+ */
+export declare function getContextLimit(id: string): number;
+/** The full ModelInfo for a model id, or undefined if it isn't a known model. */
+export declare function getModelInfo(id: string): ModelInfo | undefined;
+/** The four cumulative token totals a chat's dollar estimate is priced from. */
+export interface TokenTotals {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+}
+/**
+ * Ballpark USD cost of a chat's cumulative token consumption at first-party API
+ * list prices, or `null` for a model with no known pricing. Each token class is
+ * priced separately — input, output, cache-write (1.25× input) and cache-read
+ * (0.1× input) — because a single grand sum of "context tokens" would both
+ * double-count (each turn's input re-reflects the whole growing context, which
+ * is why {@link TokenTotals} must come from a per-turn cumulative sum) and
+ * misprice (output is 5× input, cache-read a tenth of it).
+ */
+export declare function estimateCostUsd(modelId: string, t: TokenTotals): number | null;
+/**
+ * Cost of a chat that may span several models, priced from each model's own
+ * rate. A chat's turns can run on different models (the composer lets you switch
+ * model per turn, and the project default may differ from what actually ran), so
+ * pricing the whole chat at one model — e.g. the project default — misprices by
+ * the ratio between them (a Haiku chat billed at Opus rates is 5× too high).
+ * Keys are the `message.model` recorded on each assistant turn; totals for a
+ * model with no known pricing are skipped. Returns the summed cost, or `null`
+ * only when *no* group could be priced (so an entirely-unknown-model chat hides
+ * its cost rather than showing $0.00).
+ */
+export declare function estimateCostUsdByModel(byModel: Record<string, TokenTotals>): number | null;

package/packages/server/dist/models.js

@@ -0,0 +1,208 @@
+/**
+ * Models module — the single source of truth for the Claude model ids paddock
+ * exposes (keeper + sweeper defaults, the picker list, and per-model context
+ * limits).
+ *
+ * The wire contract (CONTRACT-v3 §2/§3) and every consumer (the `/api/models`
+ * route, the project `model` resolution in projects.ts, the keeper/sweeper
+ * registration in herdctl.ts, and the context-meter math in ws.ts) read these
+ * constants — so changing the available models or a context limit is a one-file
+ * edit here.
+ *
+ * Context limits (verified against the Models API): Opus 5, Fable 5, Opus 4.8
+ * and Sonnet 5 all have a 1,000,000-token context window; Haiku 4.5 is 200,000.
+ * On the Max plan the keeper agents run Opus 5 at its full 1M window, so
+ * the context meter must use 1M for it — otherwise a long chat reads >100%.
+ */
+/**
+ * The selectable models, in picker order. The first entry is the keeper default
+ * (Opus); the cheap Haiku is the sweeper default. Order here is the order the UI
+ * renders.
+ */
+export const MODELS = [
+    {
+        id: "claude-opus-5",
+        label: "Opus 5",
+        contextLimit: 1_000_000,
+        pricing: { inputPer1M: 5, outputPer1M: 25 },
+    },
+    {
+        id: "claude-opus-4-8",
+        label: "Opus 4.8",
+        contextLimit: 1_000_000,
+        pricing: { inputPer1M: 5, outputPer1M: 25 },
+    },
+    {
+        id: "claude-fable-5",
+        label: "Fable 5",
+        contextLimit: 1_000_000,
+        pricing: { inputPer1M: 10, outputPer1M: 50 },
+    },
+    {
+        id: "claude-sonnet-5",
+        label: "Sonnet 5",
+        contextLimit: 1_000_000,
+        pricing: { inputPer1M: 3, outputPer1M: 15 },
+    },
+    {
+        id: "claude-haiku-4-5-20251001",
+        label: "Haiku 4.5",
+        contextLimit: 200_000,
+        pricing: { inputPer1M: 1, outputPer1M: 5 },
+    },
+];
+/** The model a project runs on unless the project overrides it. */
+export const DEFAULT_MODEL = "claude-opus-5";
+/**
+ * Resolve the models OFFERED (the picker/allow-list) from an optional list of
+ * allowed ids (issue #457 Step 2). {@link MODELS} stays the authoritative CATALOG
+ * — the source of every model's metadata (label/contextLimit/pricing) and the
+ * validation set for {@link isKnownModel}; this only narrows WHICH catalog models
+ * an instance/project offers.
+ *
+ * - `allowIds` undefined or empty ⇒ every catalog model is offered (today's
+ *   behaviour, fully backward-compatible).
+ * - Otherwise the catalog is filtered to `allowIds`, PRESERVING catalog order and
+ *   metadata (the returned entries are the catalog's own `ModelInfo` objects, so
+ *   an operator can't set a wrong context limit — they only pick by id).
+ * - Unknown ids in `allowIds` are ignored (they aren't in the catalog).
+ *
+ * The result may be empty only when every id was unknown; callers that must never
+ * offer zero models (the config loader) collapse that back to the full catalog.
+ */
+export function resolveModels(allowIds) {
+    if (!allowIds || allowIds.length === 0)
+        return MODELS;
+    const allow = new Set(allowIds);
+    return MODELS.filter((m) => allow.has(m.id));
+}
+/**
+ * The effective default model for a resolved model list: {@link DEFAULT_MODEL}
+ * when it's still offered, else the first offered model's id (the list is in
+ * picker order, so the first entry is the natural default). Falls back to
+ * {@link DEFAULT_MODEL} when the list is empty, so callers always get a
+ * concrete id.
+ */
+export function resolveDefaultModel(models) {
+    if (models.length === 0)
+        return DEFAULT_MODEL;
+    return models.some((m) => m.id === DEFAULT_MODEL) ? DEFAULT_MODEL : models[0].id;
+}
+/**
+ * Per-project keeper-agent settings surfaced in the project settings UI
+ * (issue #12). These mirror the fleet-wide `defaults` in herdctl.ts so a project
+ * that doesn't override a field inherits the same value it would have anyway —
+ * they're the single source of truth for both the defaults block and the DTO
+ * resolution.
+ */
+/**
+ * The keeper `permission_mode` values offered in the settings UI. A curated
+ * subset of herdctl's PermissionMode enum (default / acceptEdits / plan /
+ * bypassPermissions) — the niche delegate/dontAsk modes are omitted.
+ */
+export const PERMISSION_MODES = ["default", "acceptEdits", "plan", "bypassPermissions"];
+/** Defaults inherited when a project doesn't override the field. */
+export const DEFAULT_PERMISSION_MODE = "acceptEdits";
+export const DEFAULT_MAX_TURNS = 200;
+export const DEFAULT_DOCKER = false;
+/** Upper bound on a project's `max_turns` (guards the UI + PATCH validation). */
+export const MAX_TURNS_LIMIT = 1000;
+/**
+ * How a keeper chat turn is driven (Paddock#111):
+ *  - `batch`   — one-shot `FleetManager.trigger()` per turn (the legacy path);
+ *                the `claude` process exits at the turn boundary, so scheduled
+ *                wakeups / background tasks silently die.
+ *  - `session` — a persistent, herdctl-managed `openChatSession` per turn
+ *                (`manageLifecycle: true`); the session is reaped when idle and
+ *                its timer-class wakeups are re-triggered through the scheduler,
+ *                so cross-turn autonomy (`ScheduleWakeup`, `/loop`) actually
+ *                works. See herdctl#307 (reaper) and herdctl#303 (SDK bump).
+ */
+export const DRIVE_MODES = ["batch", "session"];
+/**
+ * Default drive mode. `session` (#316): a fresh/un-configured instance
+ * gets cross-turn autonomy (`ScheduleWakeup`, `/loop`, reaper-backed background
+ * work) and the SDK streaming runtime by default, instead of only when an
+ * operator sets `PADDOCK_DRIVE_MODE=session`. The env var and per-project
+ * `driveMode` override still take precedence; this only moves the built-in
+ * default off the legacy one-shot `batch` path.
+ */
+export const DEFAULT_DRIVE_MODE = "session";
+/** Whether `m` is one of the offered keeper permission modes. */
+export function isKnownPermissionMode(m) {
+    return PERMISSION_MODES.includes(m);
+}
+/** Whether `m` is a known keeper drive mode. */
+export function isKnownDriveMode(m) {
+    return DRIVE_MODES.includes(m);
+}
+/** Whether `n` is a valid keeper `max_turns` (positive integer within bounds). */
+export function isValidMaxTurns(n) {
+    return typeof n === "number" && Number.isInteger(n) && n >= 1 && n <= MAX_TURNS_LIMIT;
+}
+/** The cheap model the post-turn sweeper (curator) always uses. */
+export const SWEEPER_DEFAULT_MODEL = "claude-haiku-4-5-20251001";
+/** Default context limit when a model id is unknown (every current model is 200k). */
+const DEFAULT_CONTEXT_LIMIT = 200000;
+/** Whether `id` is one of the known selectable models. */
+export function isKnownModel(id) {
+    return MODELS.some((m) => m.id === id);
+}
+/**
+ * The context limit (in tokens) for a model id. Falls back to 200000 for an
+ * unknown id so the context meter never divides by an undefined/zero limit.
+ */
+export function getContextLimit(id) {
+    return MODELS.find((m) => m.id === id)?.contextLimit ?? DEFAULT_CONTEXT_LIMIT;
+}
+/** The full ModelInfo for a model id, or undefined if it isn't a known model. */
+export function getModelInfo(id) {
+    return MODELS.find((m) => m.id === id);
+}
+/** Cache-write (5-minute ephemeral) is 1.25× the input rate; cache-read is 0.1×. */
+const CACHE_WRITE_MULTIPLIER = 1.25;
+const CACHE_READ_MULTIPLIER = 0.1;
+/**
+ * Ballpark USD cost of a chat's cumulative token consumption at first-party API
+ * list prices, or `null` for a model with no known pricing. Each token class is
+ * priced separately — input, output, cache-write (1.25× input) and cache-read
+ * (0.1× input) — because a single grand sum of "context tokens" would both
+ * double-count (each turn's input re-reflects the whole growing context, which
+ * is why {@link TokenTotals} must come from a per-turn cumulative sum) and
+ * misprice (output is 5× input, cache-read a tenth of it).
+ */
+export function estimateCostUsd(modelId, t) {
+    const pricing = getModelInfo(modelId)?.pricing;
+    if (!pricing)
+        return null;
+    const { inputPer1M, outputPer1M } = pricing;
+    const usd = (t.inputTokens * inputPer1M +
+        t.cacheCreationTokens * inputPer1M * CACHE_WRITE_MULTIPLIER +
+        t.cacheReadTokens * inputPer1M * CACHE_READ_MULTIPLIER +
+        t.outputTokens * outputPer1M) /
+        1_000_000;
+    return usd;
+}
+/**
+ * Cost of a chat that may span several models, priced from each model's own
+ * rate. A chat's turns can run on different models (the composer lets you switch
+ * model per turn, and the project default may differ from what actually ran), so
+ * pricing the whole chat at one model — e.g. the project default — misprices by
+ * the ratio between them (a Haiku chat billed at Opus rates is 5× too high).
+ * Keys are the `message.model` recorded on each assistant turn; totals for a
+ * model with no known pricing are skipped. Returns the summed cost, or `null`
+ * only when *no* group could be priced (so an entirely-unknown-model chat hides
+ * its cost rather than showing $0.00).
+ */
+export function estimateCostUsdByModel(byModel) {
+    let usd = 0;
+    let priced = false;
+    for (const [modelId, totals] of Object.entries(byModel)) {
+        const c = estimateCostUsd(modelId, totals);
+        if (c == null)
+            continue;
+        usd += c;
+        priced = true;
+    }
+    return priced ? usd : null;
+}

package/packages/server/dist/openapi.d.ts

@@ -0,0 +1,66 @@
+/**
+ * OpenAPI document scaffolding for the Paddock HTTP API.
+ *
+ * The spec is *derived from the route schemas* — every REST route attaches a
+ * Fastify `schema` ({ tags, summary, description, params, querystring, body,
+ * response }) and `@fastify/swagger` (registered in app.ts before the routes)
+ * collects them into a live OpenAPI 3 document. When enabled
+ * (`PADDOCK_OPENAPI_ENABLED`) it is served at `/open-api` (Swagger UI) with the
+ * raw spec at `/open-api/json` plus the `/open-api.json` alias; the prefix is
+ * configurable via `PADDOCK_OPENAPI_PATH`. This module only provides the
+ * top-level document metadata (info, tags, security) that Fastify can't infer
+ * from routes, plus the Paddock-branded Swagger-UI mount options.
+ *
+ * IMPORTANT — the live conversational surface is NOT REST. Sending a message,
+ * streaming the reply, tool-call events, cancel, slash-commands and the live
+ * queue all flow over the WebSocket at `GET /ws` (see ws-protocol.ts). This spec
+ * documents the HTTP surface (reads + project/chat/trigger/git management +
+ * config + attachment upload/serve); the WS frame protocol is described in
+ * docs/API.md.
+ */
+import type { SwaggerOptions } from "@fastify/swagger";
+import type { FastifySwaggerUiOptions } from "@fastify/swagger-ui";
+import type { AuthConfig } from "./config.js";
+/** Tag groups — these MUST match the `tags` each route declares in its schema. */
+export declare const OPENAPI_TAGS: readonly [{
+    readonly name: "System";
+    readonly description: "Health, identity, models, fleet, instance config, voice.";
+}, {
+    readonly name: "Attachments";
+    readonly description: "Composer file uploads and serving agent-shared file bytes.";
+}, {
+    readonly name: "Git";
+    readonly description: "Repo remote state, GitHub auth, per-project status/diff/commit.";
+}, {
+    readonly name: "Projects";
+    readonly description: "Project CRUD, promote, files, changelog/overview, pins.";
+}, {
+    readonly name: "Triggers";
+    readonly description: "Unified schedule/event/webhook triggers: CRUD, runtime status, run-now.";
+}, {
+    readonly name: "Chats";
+    readonly description: "Chat (session) lifecycle: list, read messages, usage/context, fork, archive, star, rename, delete, run history, promote. NOTE: sending a message is WebSocket-only (GET /ws).";
+}];
+/**
+ * Build the @fastify/swagger options for a given app version + auth config. The
+ * security schemes and the Authentication section of the description reflect the
+ * running instance's mode (see {@link authDoc}).
+ */
+export declare function buildSwaggerOptions(version: string, auth: AuthConfig): SwaggerOptions;
+/** A logo/favicon image passed to Swagger UI ({ type, content } bytes). */
+export interface SwaggerImage {
+    type: string;
+    content: Buffer;
+}
+export interface SwaggerUiBranding {
+    /** Route prefix the UI mounts under (e.g. `/open-api`). */
+    routePrefix: string;
+    /** Topbar logo image (the Paddock horse). */
+    logo?: SwaggerImage;
+    /** Browser-tab favicon image. */
+    favicon?: SwaggerImage;
+    /** Brand accent hex (e.g. #c2603c) used for the topbar trim. */
+    accent: string;
+}
+/** Swagger-UI mount options (served at `routePrefix`, default `/open-api`), Paddock-branded. */
+export declare function buildSwaggerUiOptions(brand: SwaggerUiBranding): FastifySwaggerUiOptions;

package/packages/server/dist/openapi.js

@@ -0,0 +1,183 @@
+/** Tag groups — these MUST match the `tags` each route declares in its schema. */
+export const OPENAPI_TAGS = [
+    { name: "System", description: "Health, identity, models, fleet, instance config, voice." },
+    { name: "Attachments", description: "Composer file uploads and serving agent-shared file bytes." },
+    { name: "Git", description: "Repo remote state, GitHub auth, per-project status/diff/commit." },
+    { name: "Projects", description: "Project CRUD, promote, files, changelog/overview, pins." },
+    {
+        name: "Triggers",
+        description: "Unified schedule/event/webhook triggers: CRUD, runtime status, run-now.",
+    },
+    {
+        name: "Chats",
+        description: "Chat (session) lifecycle: list, read messages, usage/context, fork, archive, star, rename, delete, run history, promote. NOTE: sending a message is WebSocket-only (GET /ws).",
+    },
+];
+const BASE_DESCRIPTION = [
+    "HTTP API for Paddock — the Claude Code workspace platform (persistent chats, projects, unified triggers).",
+    "",
+    "This document is **generated from the server's route schemas** via `@fastify/swagger`, so it",
+    "tracks the code: a new or changed route with a schema shows up here automatically.",
+    "",
+    "**Live chat is WebSocket, not REST.** Sending a message, streaming the response, tool-call",
+    "events, cancel, slash-commands and the live queue all flow over `GET /ws`. This spec covers the",
+    "HTTP surface: reads, project/chat/trigger/git management, instance config, and attachment",
+    "upload/serve. The two-step attachment flow is: `POST .../chats/:sessionId/upload` (HTTP, here)",
+    "then reference the returned file ids in the `chat:send` WebSocket frame.",
+].join("\n");
+/**
+ * Resolve the OpenAPI security schemes + global requirement + a docs paragraph
+ * from the *running instance's* auth config. Paddock has no login of its own —
+ * auth is provider-agnostic (see AUTH.md), so the schemes reflect whichever mode
+ * this instance is configured for:
+ *
+ *  - `none`           → no scheme, no requirement (open; every request anonymous).
+ *  - `trusted-header` → apiKey in the configured identity header (proxy-injected).
+ *  - `jwt`            → bearer (when the header is `Authorization`) or apiKey in
+ *                       the configured header, verified against the JWKS.
+ *
+ * The single most important operational note: when Swagger UI is served BY an
+ * authenticated Paddock instance on the SAME origin (e.g. behind Authentik /
+ * oauth2-proxy), a "Try it out" call is a same-origin XHR that already carries
+ * the browser's SSO session — the proxy authenticates it and injects the
+ * identity, so no token needs to be pasted into the Authorize dialog at all. The
+ * Authorize button matters for the token path: calling from a different origin,
+ * or a programmatic client, or testing jwt mode without the proxy in front.
+ */
+function authDoc(auth) {
+    const header = "\n\n## Authentication\n\n";
+    const shared = "Paddock has no built-in login — authentication is provider-agnostic and handled at the edge " +
+        "(reverse proxy / IdP). **When these docs are served by the Paddock instance itself, behind your " +
+        "proxy, a `Try it out` request is a same-origin call that inherits your existing SSO session — it " +
+        "authenticates automatically, nothing to paste here.** Use the **Authorize** button only for the " +
+        "explicit-token path (a different origin, a programmatic client, or testing without the proxy).";
+    if (auth.mode === "trusted-header") {
+        return {
+            securitySchemes: {
+                proxyIdentity: {
+                    type: "apiKey",
+                    in: "header",
+                    name: auth.userHeader,
+                    description: `Trusted-header auth (\`PADDOCK_AUTH_MODE=trusted-header\`). The identity header your ` +
+                        `reverse proxy injects after SSO — here \`${auth.userHeader}\` ` +
+                        `(configurable via \`PADDOCK_AUTH_USER_HEADER\`). In production the proxy sets this and ` +
+                        `Paddock trusts it, so the app MUST be reachable only through the proxy (a direct client ` +
+                        `could otherwise forge the header).`,
+                },
+            },
+            security: [{ proxyIdentity: [] }],
+            paragraph: header +
+                shared +
+                `\n\nThis instance runs **trusted-header** mode: identity comes from the \`${auth.userHeader}\` header.`,
+        };
+    }
+    if (auth.mode === "jwt") {
+        const isBearer = auth.jwtHeader.toLowerCase() === "authorization";
+        const scheme = isBearer
+            ? {
+                bearerAuth: {
+                    type: "http",
+                    scheme: "bearer",
+                    bearerFormat: "JWT",
+                    description: "JWT auth (`PADDOCK_AUTH_MODE=jwt`). A signed token verified against the configured " +
+                        "JWKS (`PADDOCK_AUTH_JWKS_URL`), sent as `Authorization: Bearer <token>`.",
+                },
+            }
+            : {
+                jwtHeader: {
+                    type: "apiKey",
+                    in: "header",
+                    name: auth.jwtHeader,
+                    description: `JWT auth (\`PADDOCK_AUTH_MODE=jwt\`). A signed token verified against the JWKS, sent ` +
+                        `in the \`${auth.jwtHeader}\` header.`,
+                },
+            };
+        const schemeName = isBearer ? "bearerAuth" : "jwtHeader";
+        return {
+            securitySchemes: scheme,
+            security: [{ [schemeName]: [] }],
+            paragraph: header +
+                shared +
+                `\n\nThis instance runs **jwt** mode: a signed token in the \`${auth.jwtHeader}\` header, ` +
+                `verified against the JWKS.`,
+        };
+    }
+    // mode === "none"
+    return {
+        paragraph: header +
+            shared +
+            "\n\nThis instance runs **none** mode (open, unauthenticated) — every request is anonymous. " +
+            "A real deployment sits behind a proxy in `trusted-header` or `jwt` mode.",
+    };
+}
+/**
+ * Build the @fastify/swagger options for a given app version + auth config. The
+ * security schemes and the Authentication section of the description reflect the
+ * running instance's mode (see {@link authDoc}).
+ */
+export function buildSwaggerOptions(version, auth) {
+    const a = authDoc(auth);
+    return {
+        openapi: {
+            openapi: "3.0.3",
+            info: {
+                title: "Paddock HTTP API",
+                description: BASE_DESCRIPTION + a.paragraph,
+                version,
+            },
+            tags: OPENAPI_TAGS.map((t) => ({ name: t.name, description: t.description })),
+            ...(a.securitySchemes ? { components: { securitySchemes: a.securitySchemes } } : {}),
+            ...(a.security ? { security: a.security } : {}),
+        },
+        // Keep untagged routes visible rather than hidden (the /ws upgrade is hidden
+        // separately via schema.hide).
+        hideUntagged: false,
+    };
+}
+/**
+ * Custom Swagger-UI CSS: swap in the Paddock look. Darkens the topbar, sizes the
+ * injected logo, tints the trim with the brand accent, and hides the spec-URL bar
+ * (which otherwise exposes the server's own URL in the header). Everything else
+ * is stock Swagger UI.
+ */
+function brandCss(accent) {
+    return [
+        ".swagger-ui .topbar { background-color: #14181f; border-bottom: 3px solid " + accent + "; }",
+        ".swagger-ui .topbar .download-url-wrapper { display: none; }",
+        ".swagger-ui .topbar a { max-height: 40px; }",
+        ".swagger-ui .topbar a img { height: 36px; width: auto; content: normal; }",
+        ".swagger-ui .info .title small.version-stamp { background: " + accent + "; }",
+    ].join("\n");
+}
+/** Swagger-UI mount options (served at `routePrefix`, default `/open-api`), Paddock-branded. */
+export function buildSwaggerUiOptions(brand) {
+    const opts = {
+        routePrefix: brand.routePrefix,
+        uiConfig: {
+            docExpansion: "list",
+            deepLinking: true,
+            displayRequestDuration: true,
+            persistAuthorization: true,
+        },
+        theme: {
+            title: "Paddock HTTP API",
+            css: [{ filename: "paddock.css", content: brandCss(brand.accent) }],
+            ...(brand.favicon
+                ? {
+                    favicon: [
+                        {
+                            filename: "favicon.png",
+                            rel: "icon",
+                            type: brand.favicon.type,
+                            sizes: "32x32",
+                            content: brand.favicon.content,
+                        },
+                    ],
+                }
+                : {}),
+        },
+    };
+    if (brand.logo)
+        opts.logo = { type: brand.logo.type, content: brand.logo.content };
+    return opts;
+}

package/packages/server/dist/parent-detach.d.ts

@@ -0,0 +1,30 @@
+export declare class ParentDetachStore {
+    private readonly stateFile;
+    /** In-memory set of detached keys (loaded once, written through on change). */
+    private detached;
+    /**
+     * The in-flight load, cached so concurrent first-callers share ONE read — the
+     * same lost-update guard {@link ArchiveStore} carries.
+     */
+    private loadPromise;
+    /** Serialises concurrent writes so the file never interleaves. */
+    private writing;
+    constructor(dataDir: string);
+    /** Load the persisted set (lazily, deduped; tolerant of a missing/corrupt file). */
+    private ensureLoaded;
+    /**
+     * Has this chat been detached from its parent? Non-throwing: any load error
+     * reads as false, so a corrupt sidecar degrades to "nesting as recorded"
+     * rather than flattening the whole list.
+     */
+    isDetached(agent: string, sessionId: string): Promise<boolean>;
+    /**
+     * Set (or clear) a chat's detached flag, persisting the change. Idempotent;
+     * returns whether the flag actually CHANGED. Clearing it re-exposes whatever
+     * the two resolver tiers say — which is what makes re-attach free: nothing was
+     * ever destroyed, only overridden.
+     */
+    setDetached(agent: string, sessionId: string, detached: boolean): Promise<boolean>;
+    /** Write-through, serialised so overlapping toggles can't corrupt the file. */
+    private persist;
+}