@edspencer/paddock 0.0.1 → 0.57.0

package/packages/server/dist/app.js

@@ -0,0 +1,325 @@
+/**
+ * App factory — builds a fully-wired Fastify instance (REST + WS + optional
+ * static SPA) around a ProjectStore + HerdctlService + GitService + GithubAuth.
+ *
+ * Extracted from index.ts so tests can boot the REAL app in-process against a
+ * temp data dir (with a fake `claude` on PATH) without binding a port or
+ * registering signal handlers. `index.ts` calls `buildApp()` then `app.listen`.
+ *
+ * This is a testability seam only — the wiring is identical to the prior inline
+ * bootstrap; no behavior changed.
+ */
+import Fastify from "fastify";
+import websocket from "@fastify/websocket";
+import fastifyStatic from "@fastify/static";
+import fastifyMultipart from "@fastify/multipart";
+import fastifySwagger from "@fastify/swagger";
+import fastifySwaggerUi from "@fastify/swagger-ui";
+import { createRequire } from "node:module";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { loadPaddockConfig } from "./config.js";
+import { ProjectStore, ROOT_KEY } from "./projects.js";
+import { AttachmentStore } from "./attachments.js";
+import { HerdctlService } from "./herdctl.js";
+import { GitService } from "./git.js";
+import { GithubAuth } from "./github-auth.js";
+import { makeTranscriber } from "./transcribe.js";
+import { registerRoutes } from "./routes.js";
+import { registerAuth } from "./auth.js";
+import { evaluateBindSafety } from "./bind-safety.js";
+import { renderIndexHtml } from "./brand.js";
+import { makeChatHandler } from "./ws.js";
+import { SweepService } from "./sweep.js";
+import { ArchiveStore } from "./archive.js";
+import { StarStore } from "./star.js";
+import { ReadStateStore } from "./read-state.js";
+import { UnreadStore } from "./unread.js";
+import { ParentDetachStore } from "./parent-detach.js";
+import { QueuedMessageStore } from "./queued-message.js";
+import { RunProvenanceStore } from "./run-provenance.js";
+import { MessageProvenanceStore } from "./message-provenance.js";
+import { ScheduleSessionStore } from "./schedule-session.js";
+import { TriggerSessionStore } from "./trigger-session.js";
+import { PaddockEventBus } from "./event-bus.js";
+import { TriggerService } from "./triggers.js";
+import { buildSwaggerOptions, buildSwaggerUiOptions } from "./openapi.js";
+// Resolve the package version at runtime (dist/app.js → ../package.json) so the
+// generated OpenAPI document's info.version tracks the release without a build step.
+const pkgVersion = (() => {
+    try {
+        const require = createRequire(import.meta.url);
+        return require("../package.json").version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+})();
+/**
+ * True when the (query-stripped) path's last segment carries a file extension —
+ * e.g. `/assets/index-ABC.js`, `/favicon.ico`, `/sw.js`. Used by the SPA
+ * not-found handler (issue #220) to distinguish a missing static asset (→ 404)
+ * from a client-side route (→ index.html shell).
+ */
+function hasFileExtension(pathname) {
+    const last = pathname.slice(pathname.lastIndexOf("/") + 1);
+    return /\.[^./]+$/.test(last);
+}
+/**
+ * Construct and fully register the paddock app. Does NOT listen on a port and
+ * installs NO signal handlers — the caller (index.ts in prod, tests in CI)
+ * owns the lifecycle. The herdctl fleet is initialized + started; a failure
+ * there is logged and swallowed (project CRUD still works), matching prod.
+ */
+export async function buildApp(opts = {}) {
+    const cfg = opts.config ?? loadPaddockConfig();
+    const app = Fastify({
+        logger: { level: cfg.logLevel },
+    });
+    // --- safe-by-default bind guard (#435) --------------------------------
+    // Fail closed if the resolved bind host is non-loopback AND auth is `none`:
+    // that would expose an unauthenticated Paddock (which runs code + spends
+    // tokens) on a routable interface. Mirrors the jwt-without-JWKS fail-closed
+    // check below. A dangerously-worded env opt-in downgrades the refusal to a
+    // loud one-line boot warning.
+    {
+        const decision = evaluateBindSafety({
+            host: cfg.host,
+            authMode: cfg.auth.mode,
+            dangerouslyAllowOpen: cfg.dangerouslyAllowOpen,
+        });
+        if (decision.action === "refuse")
+            throw new Error(decision.message);
+        if (decision.action === "warn")
+            app.log.warn(decision.message);
+    }
+    // --- auth (provider-agnostic) -----------------------------------------
+    // Registered first so its onRequest hook guards every REST + WS request
+    // (health probes are exempted inside). Default mode `none` is a no-op. Throws
+    // on a fatal misconfig (e.g. jwt mode without a JWKS URL) — fail closed.
+    registerAuth(app, cfg.auth);
+    // --- project layer + herdctl ------------------------------------------
+    const projects = new ProjectStore(cfg.projectsRoot);
+    await projects.init();
+    const herdctl = new HerdctlService(cfg);
+    const git = new GitService(cfg.projectsRoot, cfg.gitAuthor);
+    const githubAuth = new GithubAuth(path.join(cfg.dataDir, "github-auth.json"), cfg.githubClientId);
+    const archive = new ArchiveStore(cfg.dataDir);
+    // Per-chat starred/pinned-flag sidecar (#373). Orthogonal to `archive`; the
+    // client floats starred chats to the top of both the active and Archived lists.
+    const star = new StarStore(cfg.dataDir);
+    // Per-user (or shared, in `none` mode) chat read-state sidecar (#189).
+    const readState = new ReadStateStore(cfg.dataDir);
+    // Per-user manual "unread" override sidecar (#458) — layered on read-state so a
+    // chat can be re-flagged unread after its last turn was seen ("look at it again
+    // in the morning"). Cleared whenever the chat is marked seen.
+    const unread = new UnreadStore(cfg.dataDir);
+    // Explicit "this chat was detached from its parent" sidecar (#508). Checked
+    // ahead of both parent-resolution tiers, so a detach survives the inference
+    // that would otherwise re-derive the old parent on the next list load.
+    const parentDetach = new ParentDetachStore(cfg.dataDir);
+    // Per-chat queued message sidecar (#197) for server-side auto-send.
+    const queuedMessage = new QueuedMessageStore(cfg.dataDir);
+    // Per-chat provenance sidecar (issue #261): records how each chat was created
+    // (origin human/scheduled/spawned + spawn depth) so #262 can depth-gate
+    // spawning and #267 can badge provenance. A1 only carries/persists the marker.
+    const runProvenance = new RunProvenanceStore(cfg.dataDir);
+    // Per-MESSAGE provenance sidecar (issue #290): records WHO injected each
+    // machine-added turn (send_message / schedule / spawn kickoff) so the chat
+    // history can attribute it. The per-message analog of runProvenance.
+    const messageProvenance = new MessageProvenanceStore(cfg.dataDir);
+    // Owned-session sidecar for accreting schedules (issue #265 / DD-2): maps a
+    // `resume_session: true` schedule to the one chat it accretes into across fires.
+    const scheduleSessions = new ScheduleSessionStore(cfg.dataDir);
+    // In-process lifecycle event bus (Epic T). The archive commit sites (REST route +
+    // self-MCP archive tool) `emit` onto the bus; the chat handler subscribes and fires
+    // the project's enabled event triggers via startAgentTurn.
+    const events = new PaddockEventBus();
+    // Unified trigger registry + owned-session sidecar (Epic T / T1). TriggerService is
+    // the single CRUD surface over both fire paths (event bus + schedule handler); the
+    // sidecar rebinds a `run.session: "resume"` trigger's owned chat after a restart.
+    const triggers = new TriggerService(projects, herdctl);
+    const triggerSessions = new TriggerSessionStore(cfg.dataDir);
+    // Store for files shared via mcp__paddock__send_file (issue #112). Copies live
+    // outside any project working dir so they never show up as untracked repo files.
+    const attachments = new AttachmentStore(path.join(cfg.dataDir, "attachments"));
+    await attachments.init();
+    const transcriber = makeTranscriber(cfg.transcription);
+    app.log.info({ mode: cfg.transcription.mode, available: transcriber.available }, "voice dictation capability");
+    // `list()` enumerates the root's CHILDREN (it walks subdirectories), so the
+    // root workspace itself is never in it. It always exists — the instance's own
+    // directory — so resolve it explicitly and register its keeper alongside every
+    // child's. The root keeper is an ordinary keeper in every respect.
+    const rootWorkspace = await projects.get(ROOT_KEY);
+    const initialProjects = [...(await projects.list()), rootWorkspace];
+    try {
+        await herdctl.init(initialProjects);
+        await herdctl.start();
+        app.log.info("herdctl FleetManager initialized");
+    }
+    catch (err) {
+        app.log.error({ err }, "FleetManager init/start failed — chat will be unavailable");
+    }
+    // --- post-turn curation sweep (overview + changelog) -------------------
+    const sweep = new SweepService({
+        herdctl,
+        projects,
+        dataDir: cfg.dataDir,
+        minIntervalMs: cfg.sweepMinIntervalMs,
+        budget: cfg.curation,
+        logger: app.log,
+    });
+    // --- transport ---------------------------------------------------------
+    await app.register(websocket);
+    // Multipart parses the mic-recording upload on POST /api/transcribe. The size
+    // cap mirrors the transcription config so an oversized blob is rejected before
+    // it's buffered in full.
+    await app.register(fastifyMultipart, {
+        limits: { fileSize: cfg.transcription.maxUploadBytes, files: 1 },
+    });
+    // --- OpenAPI (derived from route schemas) -----------------------------
+    // @fastify/swagger MUST register before the routes: it hooks `onRoute` to
+    // collect each route's schema into a live OpenAPI document. Swagger UI mounts
+    // at /docs and reads that document (raw spec at /docs/json). Both sit behind
+    // whatever auth mode is configured (no special exemption) — the docs are
+    // gated exactly like the API they describe. The security schemes advertised in
+    // the spec reflect this instance's auth mode (see openapi.ts / authDoc).
+    //
+    // The topbar logo + favicon are the shipped Paddock icons from the built web
+    // bundle (icons/*.png), so the docs are branded like the app; missing assets
+    // (API-only mode with no web dist) just fall back to the stock look.
+    if (cfg.openapi.enabled) {
+        const readImage = async (rel, type) => {
+            try {
+                return { type, content: await fs.readFile(path.join(cfg.webDist, rel)) };
+            }
+            catch {
+                return undefined;
+            }
+        };
+        const [swaggerLogo, swaggerFavicon] = await Promise.all([
+            readImage(path.join("icons", "icon-192.png"), "image/png"),
+            readImage(path.join("icons", "favicon-32.png"), "image/png"),
+        ]);
+        await app.register(fastifySwagger, buildSwaggerOptions(pkgVersion, cfg.auth));
+        await app.register(fastifySwaggerUi, buildSwaggerUiOptions({
+            routePrefix: cfg.openapi.path,
+            logo: swaggerLogo,
+            favicon: swaggerFavicon,
+            accent: cfg.brand.accent,
+        }));
+        // Stable, tool-friendly alias for the raw spec (e.g. `/open-api.json`), next
+        // to the UI's own `<path>/json`. Hidden from the spec itself.
+        app.get(`${cfg.openapi.path}.json`, { schema: { hide: true } }, () => app.swagger());
+        app.log.info({ path: cfg.openapi.path }, "OpenAPI reference mounted");
+    }
+    else {
+        app.log.info("OpenAPI reference off (set PADDOCK_OPENAPI_ENABLED=1 to mount /open-api)");
+    }
+    const chatHandler = makeChatHandler({ herdctl, projects, sweep, attachments, queuedMessage, runProvenance, messageProvenance, archive, scheduleSessions, events, triggers, triggerSessions, cfg });
+    // --- external Management API (#312 M1) ---------------------------------
+    // Surface how the `managementApi` block resolved. A malformed client is an
+    // ERROR (the operator wrote something meaningless); a dropped one is a WARNING
+    // (its credential wouldn't resolve, so it failed closed). Logged here because
+    // config loading has no logger of its own.
+    for (const message of cfg.managementApiDiagnostics.errors)
+        app.log.error(message);
+    for (const message of cfg.managementApiDiagnostics.warnings)
+        app.log.warn(message);
+    if (cfg.managementApi.clients.length > 0) {
+        app.log.info({
+            clients: cfg.managementApi.clients.map((c) => c.clientId),
+            instanceId: cfg.managementApi.instanceId,
+        }, "management API: /mcp enabled (self-authenticated — independent of PADDOCK_AUTH_MODE and of any proxy)");
+    }
+    else {
+        app.log.info("management API: /mcp disabled (no managementApi.clients configured) — the endpoint 404s");
+    }
+    await registerRoutes(app, { projects, herdctl, git, githubAuth, transcriber, archive, star, readState, unread, parentDetach, runProvenance, messageProvenance, attachments, fireTrigger: chatHandler.fireTrigger, managementOpsContext: chatHandler.managementOpsContext, events, triggers, cfg });
+    await app.register(async (scoped) => {
+        // `hide: true` keeps the WS upgrade out of the OpenAPI doc — it's not a REST
+        // endpoint (a Swagger "Try it out" against it would just fail); the WS frame
+        // protocol is documented in the spec description + docs/API.md instead.
+        scoped.get("/ws", { websocket: true, schema: { hide: true } }, (socket) => {
+            void chatHandler.handle(socket);
+        });
+    });
+    // --- static SPA (production) ------------------------------------------
+    const serveStatic = opts.serveStatic ?? true;
+    if (serveStatic) {
+        const hasWebDist = await fs
+            .stat(cfg.webDist)
+            .then((s) => s.isDirectory())
+            .catch(() => false);
+        if (hasWebDist) {
+            // Inject per-instance branding (issue #34) into index.html ONCE at
+            // startup, then serve that string for the app root + every client-side
+            // route.
+            const rawIndex = await fs.readFile(path.join(cfg.webDist, "index.html"), "utf8");
+            const indexHtml = renderIndexHtml(rawIndex, cfg.brand, {
+                enabled: cfg.openapi.enabled,
+                path: cfg.openapi.path,
+            });
+            const sendIndex = (reply) => reply.type("text/html; charset=utf-8").send(indexHtml);
+            // Short-circuit the app root before fastifyStatic can serve the RAW
+            // index.html (a per-file route with `wildcard: false`). An onRequest hook
+            // that replies stops routing, so we own the branded document without
+            // registering a route that would collide with the static plugin.
+            app.addHook("onRequest", async (req, reply) => {
+                if (req.method !== "GET")
+                    return;
+                const p = req.url.split("?")[0];
+                if (p === "/" || p === "/index.html")
+                    return sendIndex(reply);
+            });
+            await app.register(fastifyStatic, { root: cfg.webDist, wildcard: false });
+            app.setNotFoundHandler((req, reply) => {
+                if (req.method === "GET" &&
+                    !req.url.startsWith("/api") &&
+                    !req.url.startsWith("/ws") &&
+                    // #312: `/.well-known/` and `/mcp` are MACHINE surfaces and must 404
+                    // honestly when absent. Both are extension-less, so without this they
+                    // would fall into the client-side-route branch below and be answered
+                    // with the SPA shell + 200 — which (a) holes the fail-closed guarantee
+                    // (an unconfigured management API would "exist" at the discovery URL)
+                    // and (b) breaks MCP OAuth discovery: a client fetching the
+                    // protected-resource metadata receives HTML, fails to parse it, and
+                    // silently falls back to treating Paddock as its own authorization
+                    // server, with no error naming the real cause.
+                    !req.url.startsWith("/.well-known/") &&
+                    !req.url.startsWith("/mcp")) {
+                    // Serve the SPA shell for client-side routes — but NEVER for a request
+                    // that is clearly a missing *static asset* (a stale hashed chunk after a
+                    // deploy, or any missing file). Those must 404 (issue #220): otherwise the
+                    // browser receives index.html (text/html) for a JS/CSS module and throws
+                    // "Failed to load module script…" ("Unexpected application error: a module
+                    // script failed"), and the service worker would cache that HTML under the
+                    // asset URL and serve it indefinitely.
+                    //
+                    // A request is treated as a client-side route (→ shell) when it is a real
+                    // browser navigation (Accept: text/html, or Sec-Fetch-Mode: navigate) OR
+                    // its path has no file extension. Everything else with a file extension
+                    // (e.g. /assets/index-DEADBEEF.js, /favicon.ico) 404s. Dotted client routes
+                    // such as /projects/x/files/README.md still resolve to the shell because a
+                    // reload/deep-link of them is a navigation carrying Accept: text/html.
+                    const p = req.url.split("?")[0];
+                    const accept = String(req.headers["accept"] ?? "");
+                    const isNavigation = req.headers["sec-fetch-mode"] === "navigate" || accept.includes("text/html");
+                    if (isNavigation || !hasFileExtension(p))
+                        return sendIndex(reply);
+                }
+                return reply.code(404).send({ error: "not found" });
+            });
+            app.log.info({ webDist: cfg.webDist, brand: cfg.brand.name }, "serving built web SPA");
+        }
+        else {
+            app.log.warn({ webDist: cfg.webDist }, "web dist not found — API-only mode");
+        }
+    }
+    const close = async () => {
+        sweep.stop();
+        await herdctl.stop().catch(() => undefined);
+        await app.close().catch(() => undefined);
+    };
+    return { app, cfg, projects, herdctl, git, githubAuth, sweep, archive, star, readState, unread, parentDetach, runProvenance, queuedMessage, transcriber, events, triggers, close };
+}

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

@@ -0,0 +1,42 @@
+export declare class ArchiveStore {
+    private readonly stateFile;
+    /** In-memory set of archived keys (loaded once, written through on change). */
+    private archived;
+    /**
+     * The in-flight load, cached so concurrent first-callers share ONE read.
+     * Caching only the resolved `archived` set would let several toggles that
+     * begin before the first `fs.readFile` resolves each build their own set and
+     * race on the assignment — a lost update (last writer wins, dropping the
+     * others' keys).
+     */
+    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;
+    /** Whether a chat is archived. Non-throwing: any load error reads as false. */
+    isArchived(agent: string, sessionId: string): Promise<boolean>;
+    /**
+     * Set (or clear) a chat's archived flag, persisting the change. Idempotent.
+     * Returns whether the flag actually CHANGED — so a caller can fire an "archived"
+     * lifecycle event (Epic G / G1) exactly once per real transition, not on a
+     * redundant re-archive of an already-archived chat.
+     */
+    setArchived(agent: string, sessionId: string, archived: boolean): Promise<boolean>;
+    /**
+     * Set (or clear) the archived flag for MANY chats in ONE write (#508).
+     *
+     * The subtree actions apply an archive to a parent and every descendant. Looped
+     * one-at-a-time that's N round trips, and a failure partway leaves a torn family
+     * (parent archived, half the children not) that the user has to unpick by hand.
+     * Here the whole set lands in the in-memory set first and persists once, so the
+     * sidecar only ever holds the before or the after state.
+     *
+     * Returns the ids whose flag actually CHANGED, so the caller can fire one
+     * `onArchive` per real transition — the same contract as {@link setArchived}.
+     */
+    setManyArchived(agent: string, sessionIds: readonly string[], archived: boolean): Promise<string[]>;
+    /** Write-through, serialised so overlapping toggles can't corrupt the file. */
+    private persist;
+}

package/packages/server/dist/archive.js

@@ -0,0 +1,125 @@
+/**
+ * ArchiveStore — a Paddock-side sidecar for the per-chat "archived" flag (#95).
+ *
+ * Archiving files a finished chat away into a collapsible "Archived" section
+ * without touching its transcript, so it stays fully openable/resumable/forkable
+ * — the flag is purely presentational metadata.
+ *
+ * The natural home for this is @herdctl/core's SessionMetadataStore (the same
+ * layer that persists custom chat names), whose schema already reserves room for
+ * a future `archived` field. Until that ships upstream, Paddock keeps its own
+ * tiny JSON sidecar in the data dir — the exact same pattern SweepService uses
+ * for its watermark state. Keyed by `<agent>\0<sessionId>` (NUL-separated) so
+ * chats under different agents can never collide — a NUL can occur in neither an
+ * agent name (`keeper-<slug>`) nor a UUID. Only archived entries
+ * are stored (an unarchive deletes the key), keeping the file compact.
+ */
+import { promises as fs } from "node:fs";
+import path from "node:path";
+const STATE_FILE = "archive-state.json";
+/** Separator in a storage key; a NUL can't occur in an agent name or a UUID. */
+const KEY_SEP = "\u0000";
+/** Compose the storage key for an (agent, session) pair. */
+function keyOf(agent, sessionId) {
+    return `${agent}${KEY_SEP}${sessionId}`;
+}
+export class ArchiveStore {
+    stateFile;
+    /** In-memory set of archived keys (loaded once, written through on change). */
+    archived = null;
+    /**
+     * The in-flight load, cached so concurrent first-callers share ONE read.
+     * Caching only the resolved `archived` set would let several toggles that
+     * begin before the first `fs.readFile` resolves each build their own set and
+     * race on the assignment — a lost update (last writer wins, dropping the
+     * others' keys).
+     */
+    loadPromise = null;
+    /** Serialises concurrent writes so the file never interleaves. */
+    writing = Promise.resolve();
+    constructor(dataDir) {
+        this.stateFile = path.join(dataDir, STATE_FILE);
+    }
+    /** Load the persisted set (lazily, deduped; tolerant of a missing/corrupt file). */
+    ensureLoaded() {
+        if (this.archived)
+            return Promise.resolve(this.archived);
+        if (!this.loadPromise) {
+            this.loadPromise = (async () => {
+                let keys = [];
+                try {
+                    const raw = await fs.readFile(this.stateFile, "utf8");
+                    const parsed = JSON.parse(raw);
+                    if (Array.isArray(parsed))
+                        keys = parsed.filter((k) => typeof k === "string");
+                }
+                catch {
+                    /* missing or unreadable — start empty */
+                }
+                this.archived = new Set(keys);
+                return this.archived;
+            })();
+        }
+        return this.loadPromise;
+    }
+    /** Whether a chat is archived. Non-throwing: any load error reads as false. */
+    async isArchived(agent, sessionId) {
+        const set = await this.ensureLoaded().catch(() => new Set());
+        return set.has(keyOf(agent, sessionId));
+    }
+    /**
+     * Set (or clear) a chat's archived flag, persisting the change. Idempotent.
+     * Returns whether the flag actually CHANGED — so a caller can fire an "archived"
+     * lifecycle event (Epic G / G1) exactly once per real transition, not on a
+     * redundant re-archive of an already-archived chat.
+     */
+    async setArchived(agent, sessionId, archived) {
+        const set = await this.ensureLoaded();
+        const key = keyOf(agent, sessionId);
+        if (archived === set.has(key))
+            return false; // no-op — avoid a needless write
+        if (archived)
+            set.add(key);
+        else
+            set.delete(key);
+        await this.persist(set);
+        return true;
+    }
+    /**
+     * Set (or clear) the archived flag for MANY chats in ONE write (#508).
+     *
+     * The subtree actions apply an archive to a parent and every descendant. Looped
+     * one-at-a-time that's N round trips, and a failure partway leaves a torn family
+     * (parent archived, half the children not) that the user has to unpick by hand.
+     * Here the whole set lands in the in-memory set first and persists once, so the
+     * sidecar only ever holds the before or the after state.
+     *
+     * Returns the ids whose flag actually CHANGED, so the caller can fire one
+     * `onArchive` per real transition — the same contract as {@link setArchived}.
+     */
+    async setManyArchived(agent, sessionIds, archived) {
+        const set = await this.ensureLoaded();
+        const changed = [];
+        for (const sessionId of sessionIds) {
+            const key = keyOf(agent, sessionId);
+            if (archived === set.has(key))
+                continue; // already in the target state
+            if (archived)
+                set.add(key);
+            else
+                set.delete(key);
+            changed.push(sessionId);
+        }
+        if (changed.length)
+            await this.persist(set);
+        return changed;
+    }
+    /** Write-through, serialised so overlapping toggles can't corrupt the file. */
+    persist(set) {
+        this.writing = this.writing.then(async () => {
+            const json = JSON.stringify([...set], null, 2);
+            await fs.writeFile(this.stateFile, json, "utf8").catch(() => undefined);
+        });
+        return this.writing;
+    }
+}

package/packages/server/dist/attachments-config.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Inbound attachment config — the config foundation for issue #328 Phase 1
+ * (ChatGPT-style file/image upload in the composer, "Approach A").
+ *
+ * ── What this governs ────────────────────────────────────────────────────────
+ * A user can pick / drag / paste files into the composer; each is copied into the
+ * per-instance attachment store (reusing the `send_file` store, #112) and the
+ * keeper is pointed at the absolute paths so its `Read` tool can view them
+ * (native vision on images/PDFs). This module resolves the four knobs that gate
+ * that flow: whether it's enabled at all, a per-file size cap, a per-message file
+ * count cap, and an allow-list of file types.
+ *
+ * ── Config discipline (the `recovery`/`driveMode` pattern) ───────────────────
+ * Every field is an instance default (`PADDOCK_ATTACHMENTS_*` env, YAML instance
+ * file beneath it) with an optional PER-PROJECT override (`project.yaml` →
+ * {@link import("./projects.js").ProjectYaml.attachments}). An absent/invalid
+ * override field inherits the instance default, resolved at request time by
+ * {@link resolveAttachmentsConfig} — never baked into the DTO (mirrors how
+ * `recovery` resolves via {@link import("./recovery-config.js").resolveRecoveryConfig}).
+ * A malformed override is ignored rather than fatal so a hand-edited `project.yaml`
+ * can't wedge an upload.
+ *
+ * ── allowedTypes semantics ───────────────────────────────────────────────────
+ * Each entry is either a MIME pattern (contains `/`, `*` wildcards a segment —
+ * `image/*`, `*​/*`) or an extension (starts with `.` — `.csv`, `.ipynb`). A file
+ * is allowed if its MIME matches any MIME pattern OR its extension matches any
+ * extension entry. The sentinel `"*"` (or `"*​/*"`) allows everything (the
+ * default). The extension fallback matters because browsers report empty/generic
+ * MIME for many real attachments (`.md`, `.ts`, `.heic` → `""`/`text/plain`).
+ *
+ * NOTE: `File.type` / multipart content-type are client-provided and spoofable,
+ * so allowedTypes is a hygiene/UX guardrail, NOT a security boundary (no
+ * magic-byte sniffing in v1) — appropriate for a personal/LAN tool.
+ */
+/**
+ * Resolved attachment config — all fields concrete. Held on {@link
+ * import("./config.js").PaddockConfig.attachments} (instance defaults) and
+ * produced per-request by {@link resolveAttachmentsConfig} (project override else
+ * instance).
+ */
+export interface AttachmentsConfig {
+    /**
+     * Master switch for inbound composer uploads. Default ON. When off, the upload
+     * endpoint 403s and the composer hides its picker/drop/paste affordances. Env
+     * `PADDOCK_ATTACHMENTS_ENABLED`.
+     */
+    enabled: boolean;
+    /**
+     * Per-file size cap in megabytes (1 MB = 1024*1024 bytes). A larger file is
+     * rejected before it's written. Default 25. Env
+     * `PADDOCK_ATTACHMENTS_MAX_FILE_SIZE_MB`.
+     */
+    maxFileSizeMb: number;
+    /**
+     * How many files a single message may carry. Enforced client-side (tray cap)
+     * and server-side (per upload request + at send). Default 10. Env
+     * `PADDOCK_ATTACHMENTS_MAX_FILES_PER_MESSAGE`.
+     */
+    maxFilesPerMessage: number;
+    /**
+     * Allow-list of MIME patterns / extensions (see the module doc). Default
+     * `["*"]` (allow everything). Env `PADDOCK_ATTACHMENTS_ALLOWED_TYPES`
+     * (comma-separated); YAML/project take a real array.
+     */
+    allowedTypes: string[];
+}
+/**
+ * A per-project attachment override as stored in `project.yaml` — every field
+ * optional (an absent field inherits the instance default at request time).
+ */
+export type AttachmentsOverride = Partial<AttachmentsConfig>;
+/**
+ * The built-in attachment defaults (beneath env + YAML + per-project override):
+ * enabled, 25 MB/file, 10 files/message, allow-all.
+ */
+export declare const DEFAULT_ATTACHMENTS: AttachmentsConfig;
+/** 1 MB in bytes — the unit `maxFileSizeMb` is expressed in. */
+export declare const BYTES_PER_MB: number;
+/** The per-file size cap in BYTES for a resolved config. */
+export declare function maxFileBytes(cfg: AttachmentsConfig): number;
+/**
+ * Normalise an allowedTypes list: keep only non-blank strings, trimmed and
+ * lower-cased (MIME + extensions are case-insensitive). Returns `undefined` when
+ * nothing valid remains (so an empty list never silently means "deny all").
+ */
+export declare function sanitizeAllowedTypes(value: unknown): string[] | undefined;
+/**
+ * Validate + normalise an untrusted value (from `project.yaml` or a PATCH body)
+ * into an {@link AttachmentsOverride}, dropping any field that is missing or
+ * invalid, and returning `undefined` when nothing valid remains (so an empty
+ * override is never persisted). `enabled` must be a real boolean; the numeric
+ * knobs must be positive integers; `allowedTypes` must be a non-empty string
+ * array. Defensive by design — a malformed hand-edit degrades to "inherit the
+ * instance default", never a crash.
+ */
+export declare function sanitizeAttachmentsOverride(value: unknown): AttachmentsOverride | undefined;
+/**
+ * Resolve the effective attachment config for a request: a valid per-project
+ * override wins field-by-field; every absent field inherits the instance default.
+ * Mirrors how `recovery`/`driveMode` resolve — the override is carried on disk
+ * only for the fields explicitly set, so an absent value transparently inherits
+ * the instance (env/YAML) default. The override is re-sanitised so a corrupt
+ * on-disk value can't leak through.
+ */
+export declare function resolveAttachmentsConfig(override: AttachmentsOverride | undefined, instanceDefault: AttachmentsConfig): AttachmentsConfig;
+/**
+ * True when a file (identified by its browser-reported `mime` and its
+ * `filename`) is allowed by `allowedTypes`. Allowed if any entry matches: a
+ * MIME-pattern entry (contains `/`) is tested against `mime`; an extension entry
+ * (starts with `.`) against the filename's extension. The sentinel `"*"` /
+ * `"*​/*"` allows everything. See the module doc for why the extension fallback
+ * exists. `mime`/`filename` may be empty (browsers often omit one).
+ */
+export declare function isTypeAllowed(allowedTypes: string[], mime: string | undefined, filename: string | undefined): boolean;