@aexol/spectral 0.9.245 → 0.9.247

package/dist/server/attachments/persist.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Attachment persistence (Option A) for Studio /agent image attachments.
+ *
+ * User-attached images arrive as relay `ImageAttachment`s — either inline
+ * base64 (`data`, legacy/small) or a backend-hosted url (`url`, optionally
+ * `imageId`). LLM providers see those natively, but agent TOOLS do not: a
+ * tool such as `image_generate` (reference images) or `read` can only use
+ * normal file paths. This module writes every attachment to
+ *
+ *     <cwd>/.spectral/attachments/<sanitized sessionId>/<name>.<ext>
+ *
+ * so the prompt can be annotated with the saved absolute paths (see
+ * `formatAttachmentAnnotation`) and the agent can use the images as files.
+ *
+ * Guarantees:
+ *   - NEVER throws and never rejects: every failure (fetch error, fs error,
+ *     base64 decode) is reported through `onWarn` and the prompt proceeds.
+ *   - Idempotent: the same imageId (or content hash) always maps to the same
+ *     path, so re-sending an attachment overwrites the same file.
+ *   - Sandboxed: every path segment is stripped to `[A-Za-z0-9_-]`, so a
+ *     malicious sessionId/imageId/url can never traverse (`..` contains
+ *     only dots → stripped → falls back to a safe name).
+ *   - Capped: per-session file count and total size (both named consts).
+ *
+ * The stored session history is NEVER rewritten: callers keep persisting the
+ * original content to SQLite and only annotate the text handed to the agent.
+ *
+ * @module @spectral/server/attachments/persist
+ */
+import type { ImageAttachment } from "../wire.js";
+/** Max persisted files per session directory — beyond this, persistence is skipped. */
+export declare const MAX_FILES_PER_SESSION = 50;
+/** Max total bytes per session directory (200 MB) — beyond this, persistence is skipped. */
+export declare const MAX_TOTAL_ATTACHMENT_BYTES: number;
+/** Wall-clock budget for one `persistAttachments()` call (url fetches dominate). */
+export declare const PERSIST_DEADLINE_MS = 30000;
+/** Per-request timeout for fetching a hosted/foreign image. */
+export declare const FETCH_ATTACHMENT_TIMEOUT_MS = 10000;
+/**
+ * Strip a path segment to `[A-Za-z0-9_-]` (length-capped). `..`, `/`, `\`,
+ * percent-encodings and unicode are all removed, so traversal is impossible:
+ * a fully-stripped segment collapses to `fallback` instead of becoming `""`.
+ */
+export declare function sanitizeSegment(input: string, fallback: string): string;
+export declare function attachmentExtension(mimeType: string): string | null;
+/**
+ * Sanitized file stem for an attachment, chosen deterministically so the
+ * same attachment always maps to the same path (idempotency):
+ *   1. sanitized `imageId`,
+ *   2. hosted image id extracted from `url`,
+ *   3. sha256 of `url` (foreign urls),
+ *   4. sha256 of the inline `data` payload.
+ * `null` when the attachment has none of the above.
+ */
+export declare function attachmentFileStem(image: ImageAttachment): string | null;
+/** `stem.ext` for an attachment, or `null` when the mime/stem is unusable. */
+export declare function attachmentFileName(image: ImageAttachment): string | null;
+/** `<cwd>/.spectral/attachments` — the sweep root. Always absolute. */
+export declare function attachmentsRootFor(cwd: string): string;
+/** Per-session directory under the attachments root. Always absolute. */
+export declare function attachmentsSessionDirFor(cwd: string, sessionId: string): string;
+/** Absolute path an attachment would be persisted to, or `null` when unusable. */
+export declare function attachmentPathFor(cwd: string, sessionId: string, image: ImageAttachment): string | null;
+/**
+ * The persisted paths that still exist on disk for a message's attachments.
+ * Used by history rehydration: the annotation is only appended for files
+ * that are actually readable — an attachment persisted days ago may have
+ * been swept by `sweepAttachments()` in the meantime.
+ */
+export declare function existingAttachmentPaths(cwd: string, sessionId: string, images?: ImageAttachment[]): string[];
+/**
+ * Prompt annotation for persisted attachments, e.g.
+ * `"\n\n[Attached images saved at: /abs/a.png, /abs/b.jpg]"`.
+ * Empty string when no path survived (nothing persisted / none exist).
+ */
+export declare function formatAttachmentAnnotation(paths: readonly string[]): string;
+/**
+ * Rehydration twin of the prompt annotation: `content` plus the saved-at
+ * annotation for attachments that still exist on disk. Used by
+ * `agent-bridge.ts` when rebuilding prior user messages from
+ * `messages.images_json`, so the LLM context matches what the original
+ * prompt carried. Content is returned unchanged when nothing exists.
+ */
+export declare function annotatedUserMessageText(options: {
+    cwd: string;
+    sessionId?: string;
+    content: string;
+    images?: ImageAttachment[];
+}): string;
+/** One successfully persisted attachment. */
+export interface PersistedAttachment {
+    path: string;
+    bytes: number;
+}
+export interface PersistAttachmentsInput {
+    /** Sanitized into the directory segment — never used raw. */
+    sessionId: string;
+    /** Project cwd; attachments land under `<cwd>/.spectral/attachments/`. */
+    cwd: string;
+    images?: ImageAttachment[];
+    /**
+     * Backend routing override. `serve.ts` already resolved both (the same
+     * credentials AgentBridge uses for inference), so the server passes them
+     * in instead of re-reading config + machine store. Falls back to
+     * `resolveBackendRouting()` when omitted.
+     */
+    backendUrl?: string;
+    machineJwt?: string;
+    /** Injectable fetch for tests / alternative runtimes. */
+    fetchImpl?: typeof fetch;
+    /** Diagnostics sink — failures warn and continue. */
+    onWarn?: (message: string) => void;
+    /** Deadline override (tests). Defaults to `PERSIST_DEADLINE_MS`. */
+    deadlineMs?: number;
+}
+/**
+ * Persist every usable attachment of a user message to disk and return the
+ * saved absolute paths (annotation input). NEVER throws and never rejects:
+ * every per-image failure warns and continues, and the prompt must always
+ * proceed — a missing file is a degradation, not an error.
+ *
+ * Per-image flow:
+ *   - `{data}` → base64-decoded and written directly,
+ *   - `{url}`  → bytes fetched through the hosted resolver machinery.
+ *
+ * Skips (with a warning) when: the mime type is outside the allowlist, the
+ * per-session file cap / total size cap / wall-clock deadline is reached, or
+ * the fetch/write fails.
+ */
+export declare function persistAttachments(input: PersistAttachmentsInput): Promise<PersistedAttachment[]>;
+//# sourceMappingURL=persist.d.ts.map

package/dist/server/attachments/persist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persist.d.ts","sourceRoot":"","sources":["../../../src/server/attachments/persist.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAaH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AASlD,uFAAuF;AACvF,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAExC,4FAA4F;AAC5F,eAAO,MAAM,0BAA0B,QAAoB,CAAC;AAE5D,oFAAoF;AACpF,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAE1C,+DAA+D;AAC/D,eAAO,MAAM,2BAA2B,QAAS,CAAC;AAiBlD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGvE;AAeD,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAInE;AAMD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,GAAG,IAAI,CAYxE;AAED,8EAA8E;AAC9E,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,GAAG,IAAI,CAMxE;AAED,uEAAuE;AACvE,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED,yEAAyE;AACzE,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAE/E;AAED,kFAAkF;AAClF,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,eAAe,GACrB,MAAM,GAAG,IAAI,CAIf;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,eAAe,EAAE,GACzB,MAAM,EAAE,CAaV;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAM3E;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE;IAChD,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,eAAe,EAAE,CAAC;CAC5B,GAAG,MAAM,CAGT;AAED,6CAA6C;AAC7C,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,uBAAuB;IACtC,6DAA6D;IAC7D,SAAS,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,eAAe,EAAE,CAAC;IAC3B;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yDAAyD;IACzD,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,qDAAqD;IACrD,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AA4JD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,uBAAuB,GAC7B,OAAO,CAAC,mBAAmB,EAAE,CAAC,CA8EhC"}

package/dist/server/attachments/persist.js

@@ -0,0 +1,406 @@
+/**
+ * Attachment persistence (Option A) for Studio /agent image attachments.
+ *
+ * User-attached images arrive as relay `ImageAttachment`s — either inline
+ * base64 (`data`, legacy/small) or a backend-hosted url (`url`, optionally
+ * `imageId`). LLM providers see those natively, but agent TOOLS do not: a
+ * tool such as `image_generate` (reference images) or `read` can only use
+ * normal file paths. This module writes every attachment to
+ *
+ *     <cwd>/.spectral/attachments/<sanitized sessionId>/<name>.<ext>
+ *
+ * so the prompt can be annotated with the saved absolute paths (see
+ * `formatAttachmentAnnotation`) and the agent can use the images as files.
+ *
+ * Guarantees:
+ *   - NEVER throws and never rejects: every failure (fetch error, fs error,
+ *     base64 decode) is reported through `onWarn` and the prompt proceeds.
+ *   - Idempotent: the same imageId (or content hash) always maps to the same
+ *     path, so re-sending an attachment overwrites the same file.
+ *   - Sandboxed: every path segment is stripped to `[A-Za-z0-9_-]`, so a
+ *     malicious sessionId/imageId/url can never traverse (`..` contains
+ *     only dots → stripped → falls back to a safe name).
+ *   - Capped: per-session file count and total size (both named consts).
+ *
+ * The stored session history is NEVER rewritten: callers keep persisting the
+ * original content to SQLite and only annotate the text handed to the agent.
+ *
+ * @module @spectral/server/attachments/persist
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, statSync, writeFileSync, } from "node:fs";
+import { join, resolve } from "node:path";
+import { extractHostedImageId, isHostedImageUrl, resolveHostedImageUrl, } from "../../backend/generated-images.js";
+import { resolveBackendRouting } from "../../backend/machine-routing.js";
+/** Max persisted files per session directory — beyond this, persistence is skipped. */
+export const MAX_FILES_PER_SESSION = 50;
+/** Max total bytes per session directory (200 MB) — beyond this, persistence is skipped. */
+export const MAX_TOTAL_ATTACHMENT_BYTES = 200 * 1024 * 1024;
+/** Wall-clock budget for one `persistAttachments()` call (url fetches dominate). */
+export const PERSIST_DEADLINE_MS = 30_000;
+/** Per-request timeout for fetching a hosted/foreign image. */
+export const FETCH_ATTACHMENT_TIMEOUT_MS = 10_000;
+/** Longest sanitized segment. Mirrors the backend image-id cap of 64 chars. */
+const MAX_SEGMENT_LENGTH = 64;
+/** Fallback segment when sanitization strips everything. */
+const FALLBACK_SESSION_SEGMENT = "session";
+/** Directory name under the project cwd. */
+const ATTACHMENTS_DIR = join(".spectral", "attachments");
+/**
+ * Characters allowed in a path segment. Anything else — dots (so `..` can
+ * never survive), slashes, backslashes, unicode, spaces — is stripped.
+ */
+const UNSAFE_SEGMENT_CHARS = /[^A-Za-z0-9_-]/g;
+/**
+ * Strip a path segment to `[A-Za-z0-9_-]` (length-capped). `..`, `/`, `\`,
+ * percent-encodings and unicode are all removed, so traversal is impossible:
+ * a fully-stripped segment collapses to `fallback` instead of becoming `""`.
+ */
+export function sanitizeSegment(input, fallback) {
+    const cleaned = input.replace(UNSAFE_SEGMENT_CHARS, "").slice(0, MAX_SEGMENT_LENGTH);
+    return cleaned.length > 0 ? cleaned : fallback;
+}
+/**
+ * File extension for an attachment, from an allowlist of image mime types:
+ * png/jpg/jpeg/webp/gif ONLY. `null` for anything else (svg, pdf, ...) —
+ * such attachments are never persisted.
+ */
+const EXTENSION_BY_MIME = {
+    "image/png": "png",
+    "image/jpg": "jpg",
+    "image/jpeg": "jpg",
+    "image/webp": "webp",
+    "image/gif": "gif",
+};
+export function attachmentExtension(mimeType) {
+    if (typeof mimeType !== "string")
+        return null;
+    const base = mimeType.split(";")[0]?.trim().toLowerCase() ?? "";
+    return EXTENSION_BY_MIME[base] ?? null;
+}
+function sha256Hex(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+/**
+ * Sanitized file stem for an attachment, chosen deterministically so the
+ * same attachment always maps to the same path (idempotency):
+ *   1. sanitized `imageId`,
+ *   2. hosted image id extracted from `url`,
+ *   3. sha256 of `url` (foreign urls),
+ *   4. sha256 of the inline `data` payload.
+ * `null` when the attachment has none of the above.
+ */
+export function attachmentFileStem(image) {
+    const imageId = typeof image.imageId === "string" ? image.imageId.trim() : "";
+    if (imageId)
+        return sanitizeSegment(imageId, "");
+    const url = typeof image.url === "string" ? image.url.trim() : "";
+    if (url) {
+        const hostedId = extractHostedImageId(url);
+        if (hostedId)
+            return sanitizeSegment(hostedId, "");
+        return sanitizeSegment(sha256Hex(url), "");
+    }
+    const data = typeof image.data === "string" ? image.data : "";
+    if (data)
+        return sanitizeSegment(sha256Hex(data), "");
+    return null;
+}
+/** `stem.ext` for an attachment, or `null` when the mime/stem is unusable. */
+export function attachmentFileName(image) {
+    const ext = attachmentExtension(image.mimeType);
+    if (!ext)
+        return null;
+    const stem = attachmentFileStem(image);
+    if (!stem)
+        return null;
+    return `${stem}.${ext}`;
+}
+/** `<cwd>/.spectral/attachments` — the sweep root. Always absolute. */
+export function attachmentsRootFor(cwd) {
+    return join(resolve(cwd), ATTACHMENTS_DIR);
+}
+/** Per-session directory under the attachments root. Always absolute. */
+export function attachmentsSessionDirFor(cwd, sessionId) {
+    return join(attachmentsRootFor(cwd), sanitizeSegment(sessionId, FALLBACK_SESSION_SEGMENT));
+}
+/** Absolute path an attachment would be persisted to, or `null` when unusable. */
+export function attachmentPathFor(cwd, sessionId, image) {
+    const name = attachmentFileName(image);
+    if (!name)
+        return null;
+    return join(attachmentsSessionDirFor(cwd, sessionId), name);
+}
+/**
+ * The persisted paths that still exist on disk for a message's attachments.
+ * Used by history rehydration: the annotation is only appended for files
+ * that are actually readable — an attachment persisted days ago may have
+ * been swept by `sweepAttachments()` in the meantime.
+ */
+export function existingAttachmentPaths(cwd, sessionId, images) {
+    if (!sessionId || !images || images.length === 0)
+        return [];
+    const out = [];
+    for (const image of images) {
+        const path = attachmentPathFor(cwd, sessionId, image);
+        if (!path)
+            continue;
+        try {
+            if (existsSync(path) && statSync(path).isFile())
+                out.push(path);
+        }
+        catch {
+            // Unreadable → treat as missing.
+        }
+    }
+    return out;
+}
+/**
+ * Prompt annotation for persisted attachments, e.g.
+ * `"\n\n[Attached images saved at: /abs/a.png, /abs/b.jpg]"`.
+ * Empty string when no path survived (nothing persisted / none exist).
+ */
+export function formatAttachmentAnnotation(paths) {
+    const unique = [
+        ...new Set(paths.filter((p) => typeof p === "string" && p.length > 0)),
+    ];
+    if (unique.length === 0)
+        return "";
+    return `\n\n[Attached images saved at: ${unique.join(", ")}]`;
+}
+/**
+ * Rehydration twin of the prompt annotation: `content` plus the saved-at
+ * annotation for attachments that still exist on disk. Used by
+ * `agent-bridge.ts` when rebuilding prior user messages from
+ * `messages.images_json`, so the LLM context matches what the original
+ * prompt carried. Content is returned unchanged when nothing exists.
+ */
+export function annotatedUserMessageText(options) {
+    const saved = existingAttachmentPaths(options.cwd, options.sessionId ?? "", options.images);
+    return options.content + formatAttachmentAnnotation(saved);
+}
+/**
+ * Standard base64 alphabet (padding validated separately). Node's
+ * `Buffer.from(..., "base64")` silently IGNORES invalid characters, so a
+ * corrupt payload would decode into garbage bytes without this check.
+ */
+const BASE64_PATTERN = /^[A-Za-z0-9+/]+={0,2}$/;
+/**
+ * Decode a base64 payload (tolerating a legacy `data:` URI prefix).
+ * Strict: payloads carrying characters outside the base64 alphabet are
+ * rejected instead of silently decoded into garbage.
+ */
+function decodeBase64(value) {
+    const comma = value.indexOf(",");
+    const payload = value.startsWith("data:") && comma !== -1 ? value.slice(comma + 1) : value;
+    const compact = payload.replace(/\s+/g, "");
+    if (!compact || !BASE64_PATTERN.test(compact))
+        return null;
+    try {
+        const decoded = new Uint8Array(Buffer.from(compact, "base64"));
+        return decoded.byteLength > 0 ? decoded : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function tryFetchBytes(url, headers, options) {
+    const fetchImpl = options.fetchImpl ?? ((...args) => fetch(...args));
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), FETCH_ATTACHMENT_TIMEOUT_MS);
+    try {
+        const response = await fetchImpl(url, { signal: controller.signal, headers });
+        if (!response.ok) {
+            options.onWarn?.(`Attachment fetch failed for ${url}: HTTP ${response.status}`);
+            return null;
+        }
+        const buffer = await response.arrayBuffer();
+        if (buffer.byteLength === 0) {
+            options.onWarn?.(`Attachment fetch for ${url} returned an empty body`);
+            return null;
+        }
+        return new Uint8Array(buffer);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        options.onWarn?.(`Attachment fetch failed for ${url}: ${message}`);
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Fetch the bytes behind an attachment's url.
+ *
+ * Backend-hosted urls are fetched through the presigned-url machinery
+ * (`resolveHostedImageUrl` — machine-JWT-authed `GET /generated-images/<id>/url`,
+ * cached in `generated-images.ts`), with a fallback to an authenticated
+ * direct download from the backend itself. Foreign urls are fetched
+ * anonymously — the machine JWT is NEVER attached to a non-backend origin
+ * (`isHostedImageUrl` is the gate). Returns `null` on any failure.
+ */
+async function fetchAttachmentBytes(image, routing, options) {
+    const url = typeof image.url === "string" ? image.url.trim() : "";
+    if (!url)
+        return null;
+    const hosted = routing !== null && isHostedImageUrl(url, routing.backendUrl);
+    if (routing && hosted) {
+        const imageId = typeof image.imageId === "string" && image.imageId.trim() ? image.imageId.trim() : undefined;
+        const presigned = await resolveHostedImageUrl({
+            backendUrl: routing.backendUrl,
+            token: routing.machineJwt,
+            ...(imageId ? { imageId } : {}),
+            url,
+            fetchImpl: options.fetchImpl,
+            timeoutMs: FETCH_ATTACHMENT_TIMEOUT_MS,
+            onWarn: options.onWarn,
+        });
+        if (presigned) {
+            const bytes = await tryFetchBytes(presigned.url, undefined, options);
+            if (bytes)
+                return bytes;
+        }
+        // Fallback: authenticated direct download. The endpoint 302-redirects to
+        // a presigned S3 GET; fetch strips the Authorization header on
+        // cross-origin redirects, so the JWT never reaches storage.
+        const downloadUrl = url.startsWith("/")
+            ? `${routing.backendUrl.replace(/\/+$/, "")}${url}`
+            : url;
+        return await tryFetchBytes(downloadUrl, { Authorization: `Bearer ${routing.machineJwt}` }, options);
+    }
+    if (!routing && extractHostedImageId(url) !== null) {
+        // A hosted-backend reference with no usable machine JWT: the anonymous
+        // fetch below is a guaranteed 401, so skip with a warning instead.
+        options.onWarn?.("Not logged in (no machine routing) — skipping hosted attachment persistence");
+        return null;
+    }
+    return await tryFetchBytes(url, undefined, options);
+}
+/** File count + total bytes of the files in a session directory. */
+function sessionDirUsage(dir) {
+    let files = 0;
+    let bytes = 0;
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return { files, bytes };
+    }
+    for (const entry of entries) {
+        if (!entry.isFile())
+            continue;
+        try {
+            bytes += statSync(join(dir, entry.name)).size;
+            files += 1;
+        }
+        catch {
+            // Skip unreadable entries — usage is best-effort.
+        }
+    }
+    return { files, bytes };
+}
+/**
+ * Drop a `.gitignore` (containing `*` + `!.gitignore`) into the attachments
+ * root at first use, so persisted attachments are never committed regardless
+ * of the user's own gitignore. Best-effort.
+ */
+function ensureAttachmentsGitignore(root, onWarn) {
+    const gitignore = join(root, ".gitignore");
+    if (existsSync(gitignore))
+        return;
+    try {
+        writeFileSync(gitignore, "*\n!.gitignore\n", "utf8");
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        onWarn?.(`Could not write ${gitignore}: ${message}`);
+    }
+}
+const defaultOnWarn = (message) => {
+    console.warn(`[spectral] warn: ${message}`);
+};
+/**
+ * Persist every usable attachment of a user message to disk and return the
+ * saved absolute paths (annotation input). NEVER throws and never rejects:
+ * every per-image failure warns and continues, and the prompt must always
+ * proceed — a missing file is a degradation, not an error.
+ *
+ * Per-image flow:
+ *   - `{data}` → base64-decoded and written directly,
+ *   - `{url}`  → bytes fetched through the hosted resolver machinery.
+ *
+ * Skips (with a warning) when: the mime type is outside the allowlist, the
+ * per-session file cap / total size cap / wall-clock deadline is reached, or
+ * the fetch/write fails.
+ */
+export async function persistAttachments(input) {
+    const saved = [];
+    const onWarn = input.onWarn ?? defaultOnWarn;
+    const images = Array.isArray(input.images) ? input.images : [];
+    const candidates = images
+        .map((image) => ({ image, name: attachmentFileName(image) }))
+        .filter((c) => c.name !== null);
+    if (candidates.length === 0)
+        return saved;
+    const sessionDir = attachmentsSessionDirFor(input.cwd, input.sessionId);
+    try {
+        mkdirSync(sessionDir, { recursive: true });
+        ensureAttachmentsGitignore(attachmentsRootFor(input.cwd), onWarn);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        onWarn?.(`Could not create attachment directory ${sessionDir}: ${message} — continuing without persisted attachments`);
+        return saved;
+    }
+    let cachedRouting;
+    const getRouting = async () => {
+        if (input.backendUrl && input.machineJwt) {
+            return { backendUrl: input.backendUrl, machineJwt: input.machineJwt };
+        }
+        return (cachedRouting ??= await resolveBackendRouting().catch(() => null));
+    };
+    const usage = sessionDirUsage(sessionDir);
+    const deadlineAt = Date.now() + (input.deadlineMs ?? PERSIST_DEADLINE_MS);
+    for (const candidate of candidates) {
+        if (Date.now() > deadlineAt) {
+            onWarn?.(`Attachment persistence deadline (${input.deadlineMs ?? PERSIST_DEADLINE_MS}ms) reached — skipping remaining images`);
+            break;
+        }
+        if (usage.files >= MAX_FILES_PER_SESSION) {
+            onWarn?.(`Attachment file cap reached for session ${input.sessionId} (${MAX_FILES_PER_SESSION} files) — skipping ${candidate.name}`);
+            break;
+        }
+        const targetPath = join(sessionDir, candidate.name);
+        try {
+            let bytes = null;
+            const data = typeof candidate.image.data === "string" ? candidate.image.data : "";
+            if (data) {
+                bytes = decodeBase64(data);
+                if (!bytes)
+                    onWarn?.(`Attachment ${candidate.name} has undecodable base64 — skipped`);
+            }
+            else if (candidate.image.url) {
+                bytes = await fetchAttachmentBytes(candidate.image, await getRouting(), { fetchImpl: input.fetchImpl, onWarn });
+            }
+            if (!bytes)
+                continue;
+            if (usage.bytes + bytes.byteLength > MAX_TOTAL_ATTACHMENT_BYTES) {
+                onWarn?.(`Attachment size cap reached for session ${input.sessionId} ` +
+                    `(${MAX_TOTAL_ATTACHMENT_BYTES} bytes) — skipping ${candidate.name}`);
+                break;
+            }
+            writeFileSync(targetPath, bytes);
+            usage.files += 1;
+            usage.bytes += bytes.byteLength;
+            saved.push({ path: targetPath, bytes: bytes.byteLength });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            onWarn?.(`Failed to persist attachment ${candidate.name}: ${message}`);
+            continue;
+        }
+    }
+    return saved;
+}

package/dist/server/handlers/secrets.d.ts

@@ -0,0 +1,40 @@
+/**
+ * REST handlers for the local secret store.
+ *
+ * Contract (shared with the landing frontend):
+ *  - `GET  /api/secrets`        → `{ secrets: SecretMeta[] }` — metadata only,
+ *                                 values are NEVER returned by anything.
+ *  - `POST /api/secrets`        → `{ secret: SecretMeta }` — body
+ *                                 `{ name, value }`.
+ *  - `DELETE /api/secrets/:name` → `{ ok: true }`.
+ *
+ * Name normalization/validation and the 64 KiB value cap live in
+ * `src/secrets/store.ts`. Errors follow the existing handler error shape
+ * (`BadRequestError`/`NotFoundError` → 400/404 in the relay rest loop).
+ *
+ * SECURITY: no handler here (or anywhere in the relay loop) logs a request or
+ * response value. Only names appear in error messages, and only after they
+ * have passed `normalizeSecretName` (letters/digits/underscores).
+ */
+import { type SecretMeta } from "../../secrets/index.js";
+/**
+ * `GET /api/secrets` — list secrets as metadata only.
+ */
+export declare function handleListSecrets(): {
+    secrets: SecretMeta[];
+};
+/**
+ * `POST /api/secrets` — create or update a secret. Body: `{ name, value }`.
+ * Returns the metadata-only view; the stored value is never echoed back.
+ */
+export declare function handleSetSecret(body: Record<string, unknown>): {
+    secret: SecretMeta;
+};
+/**
+ * `DELETE /api/secrets/:name` — delete a secret. Throws `NotFoundError` (404)
+ * when the name is not stored.
+ */
+export declare function handleDeleteSecret(rawName: string): {
+    ok: true;
+};
+//# sourceMappingURL=secrets.d.ts.map

package/dist/server/handlers/secrets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.d.ts","sourceRoot":"","sources":["../../../src/server/handlers/secrets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAON,KAAK,UAAU,EACf,MAAM,wBAAwB,CAAC;AAUhC;;GAEG;AACH,wBAAgB,iBAAiB,IAAI;IAAE,OAAO,EAAE,UAAU,EAAE,CAAA;CAAE,CAE7D;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IAAE,MAAM,EAAE,UAAU,CAAA;CAAE,CAerF;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,CAiBhE"}

package/dist/server/handlers/secrets.js

@@ -0,0 +1,78 @@
+/**
+ * REST handlers for the local secret store.
+ *
+ * Contract (shared with the landing frontend):
+ *  - `GET  /api/secrets`        → `{ secrets: SecretMeta[] }` — metadata only,
+ *                                 values are NEVER returned by anything.
+ *  - `POST /api/secrets`        → `{ secret: SecretMeta }` — body
+ *                                 `{ name, value }`.
+ *  - `DELETE /api/secrets/:name` → `{ ok: true }`.
+ *
+ * Name normalization/validation and the 64 KiB value cap live in
+ * `src/secrets/store.ts`. Errors follow the existing handler error shape
+ * (`BadRequestError`/`NotFoundError` → 400/404 in the relay rest loop).
+ *
+ * SECURITY: no handler here (or anywhere in the relay loop) logs a request or
+ * response value. Only names appear in error messages, and only after they
+ * have passed `normalizeSecretName` (letters/digits/underscores).
+ */
+import { SecretNameError, SecretValueError, deleteSecret, listSecrets, normalizeSecretName, setSecret, } from "../../secrets/index.js";
+import { BadRequestError, NotFoundError } from "./errors.js";
+function toBadRequest(err) {
+    if (err instanceof SecretNameError || err instanceof SecretValueError) {
+        return new BadRequestError(err.message);
+    }
+    return null;
+}
+/**
+ * `GET /api/secrets` — list secrets as metadata only.
+ */
+export function handleListSecrets() {
+    return { secrets: listSecrets() };
+}
+/**
+ * `POST /api/secrets` — create or update a secret. Body: `{ name, value }`.
+ * Returns the metadata-only view; the stored value is never echoed back.
+ */
+export function handleSetSecret(body) {
+    if (typeof body.name !== "string" || body.name.trim() === "") {
+        throw new BadRequestError("name (string) is required");
+    }
+    if (typeof body.value !== "string") {
+        throw new BadRequestError("value (string) is required");
+    }
+    try {
+        const secret = setSecret(body.name, body.value);
+        return { secret };
+    }
+    catch (err) {
+        const mapped = toBadRequest(err);
+        if (mapped)
+            throw mapped;
+        throw err;
+    }
+}
+/**
+ * `DELETE /api/secrets/:name` — delete a secret. Throws `NotFoundError` (404)
+ * when the name is not stored.
+ */
+export function handleDeleteSecret(rawName) {
+    if (typeof rawName !== "string" || rawName.trim() === "") {
+        throw new BadRequestError("name (string) is required");
+    }
+    let name;
+    try {
+        name = normalizeSecretName(rawName);
+    }
+    catch (err) {
+        const mapped = toBadRequest(err);
+        if (mapped)
+            throw mapped;
+        throw err;
+    }
+    const deleted = deleteSecret(name);
+    if (!deleted) {
+        throw new NotFoundError(`Secret ${name} not found`);
+    }
+    return { ok: true };
+}

package/dist/server/session-stream.d.ts

@@ -423,6 +423,11 @@ export declare class SessionStreamManager {
     private readonly onCloudAgentsAuthRejected;
     private readonly broker;
     private readonly streams;
+    /**
+     * Opportunistic attachment GC runs at most once per manager lifetime
+     * (first prompt). `false` until the fire-and-forget sweep is scheduled.
+     */
+    private attachmentsSweepRan;
     /**
      * In-flight `attach` per session. Serializes concurrent attaches so the
      * `subscribe` + first `client_message` race cannot create two independent