@hyperdrive.bot/fleet-server 0.3.99

package/dist/server/server/update/state.js

@@ -0,0 +1,65 @@
+import { readFileSync, writeFileSync, renameSync, mkdirSync } from "node:fs";
+import path from "node:path";
+export const EMPTY_UPDATE_STATE = {
+    pinned: null,
+    pinnedReason: null,
+    lastInstalled: null,
+    lastCheckedAt: null,
+    lastSeenVersion: null,
+    installId: null,
+};
+function statePath(paseoHome) {
+    return path.join(paseoHome, "update-state.json");
+}
+/** Read state, returning defaults for a missing or unparseable file. */
+export function readUpdateState(paseoHome) {
+    try {
+        const raw = readFileSync(statePath(paseoHome), "utf8");
+        const parsed = JSON.parse(raw);
+        return {
+            pinned: typeof parsed.pinned === "string" ? parsed.pinned : null,
+            pinnedReason: typeof parsed.pinnedReason === "string" ? parsed.pinnedReason : null,
+            lastInstalled: typeof parsed.lastInstalled === "string" ? parsed.lastInstalled : null,
+            lastCheckedAt: typeof parsed.lastCheckedAt === "number" ? parsed.lastCheckedAt : null,
+            lastSeenVersion: typeof parsed.lastSeenVersion === "string" ? parsed.lastSeenVersion : null,
+            installId: typeof parsed.installId === "string" ? parsed.installId : null,
+        };
+    }
+    catch {
+        // A corrupt state file must not stop the daemon booting. Losing it means one
+        // extra registry check and a re-rolled bucket, both harmless.
+        return { ...EMPTY_UPDATE_STATE };
+    }
+}
+/** Merge a patch into state and write it atomically. */
+export function writeUpdateState(paseoHome, patch) {
+    const next = { ...readUpdateState(paseoHome), ...patch };
+    const target = statePath(paseoHome);
+    mkdirSync(path.dirname(target), { recursive: true });
+    // Write-then-rename: a torn state file would be read as "no state" on next boot,
+    // silently un-pinning a version known to crash.
+    const tmp = `${target}.tmp-${process.pid}`;
+    writeFileSync(tmp, `${JSON.stringify(next, null, 2)}\n`);
+    renameSync(tmp, target);
+    return next;
+}
+/** True when this version previously failed and must not be auto-installed. */
+export function isPinned(state, version) {
+    return state.pinned !== null && state.pinned === version;
+}
+/**
+ * Stable install id, created on first use.
+ *
+ * Not a machine fingerprint on purpose: it only needs to be stable and uniformly
+ * distributed to seed the rollout bucket.
+ */
+export function ensureInstallId(paseoHome, generate) {
+    const state = readUpdateState(paseoHome);
+    if (state.installId) {
+        return state.installId;
+    }
+    const installId = generate();
+    writeUpdateState(paseoHome, { installId });
+    return installId;
+}
+//# sourceMappingURL=state.js.map

package/dist/server/server/uploads/file-attachment-validation.d.ts

@@ -0,0 +1,61 @@
+/**
+ * One finalized inbound upload, recorded by the Session at the `FileEnd` finalize site
+ * (story 2.1) and looked up when a later `send_agent_message` references the `fileId`.
+ *
+ * `agentId` is the VERBATIM client-supplied identifier from `files.upload.begin.request`
+ * (the same string story 2.2 uses to build the staging dir). It is compared with `===`
+ * against `msg.agentId` on the message — never resolved through `resolveAgentIdentifier`.
+ * `stagedPath` is the server-constructed path; the client-supplied attachment `path` is
+ * never trusted — the canonical path is always re-derived from `stagedPath` via realpath.
+ */
+export interface StagedUploadRecord {
+    fileId: string;
+    agentId: string;
+    stagedPath: string;
+    size: number;
+    mimeType: string;
+    fileName: string;
+}
+/**
+ * Why a `file` attachment was rejected. Each maps to a fail-closed outcome — an attachment
+ * the user added must never be silently dropped from the dispatched prompt.
+ */
+export type FileAttachmentError = "unknown_file_id" | "cross_agent_file_id" | "staging_path_escape" | "file_missing";
+/**
+ * Result of validating one `file` attachment. On success it carries the canonical,
+ * symlink-resolved server path that the caller overwrites onto the attachment.
+ */
+export type FileAttachmentResolution = {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    error: FileAttachmentError;
+};
+/**
+ * Validate a single staged `file` attachment against the agent's upload staging area.
+ *
+ * Pure (the caller owns the registry and passes the already-looked-up record), so this is
+ * trivially unit-testable against an adversarial table. Checks run in order so the most
+ * specific failure wins:
+ *
+ *   (a) no record for the `fileId`          → `unknown_file_id`
+ *   (b) record belongs to a different agent  → `cross_agent_file_id`
+ *   (c) `realpathSync` throws (file gone)    → `file_missing`
+ *   (d) resolved path escapes the agent dir  → `staging_path_escape`
+ *   (e) otherwise                            → `{ ok: true, path: <realpath> }`
+ *
+ * `realpathSync` follows symlinks, so a symlink whose target lives outside the agent staging
+ * dir is caught by the containment check in (d) — the resolved path can never escape.
+ *
+ * @param args.paseoHome - the daemon's resolved `$PASEO_HOME`
+ * @param args.agentId - the client-supplied agent identifier (`msg.agentId`), the staging scope key
+ * @param args.record - the looked-up registry record for the attachment's `fileId`, or undefined
+ * @returns an accepted resolution carrying the canonical realpath, or a typed rejection
+ */
+export declare function resolveStagedFileAttachment(args: {
+    paseoHome: string;
+    agentId: string;
+    record: StagedUploadRecord | undefined;
+}): FileAttachmentResolution;
+//# sourceMappingURL=file-attachment-validation.d.ts.map

package/dist/server/server/uploads/file-attachment-validation.js

@@ -0,0 +1,56 @@
+import { realpathSync } from "node:fs";
+import * as path from "node:path";
+/**
+ * Validate a single staged `file` attachment against the agent's upload staging area.
+ *
+ * Pure (the caller owns the registry and passes the already-looked-up record), so this is
+ * trivially unit-testable against an adversarial table. Checks run in order so the most
+ * specific failure wins:
+ *
+ *   (a) no record for the `fileId`          → `unknown_file_id`
+ *   (b) record belongs to a different agent  → `cross_agent_file_id`
+ *   (c) `realpathSync` throws (file gone)    → `file_missing`
+ *   (d) resolved path escapes the agent dir  → `staging_path_escape`
+ *   (e) otherwise                            → `{ ok: true, path: <realpath> }`
+ *
+ * `realpathSync` follows symlinks, so a symlink whose target lives outside the agent staging
+ * dir is caught by the containment check in (d) — the resolved path can never escape.
+ *
+ * @param args.paseoHome - the daemon's resolved `$PASEO_HOME`
+ * @param args.agentId - the client-supplied agent identifier (`msg.agentId`), the staging scope key
+ * @param args.record - the looked-up registry record for the attachment's `fileId`, or undefined
+ * @returns an accepted resolution carrying the canonical realpath, or a typed rejection
+ */
+export function resolveStagedFileAttachment(args) {
+    const { paseoHome, agentId, record } = args;
+    if (!record) {
+        return { ok: false, error: "unknown_file_id" };
+    }
+    if (record.agentId !== agentId) {
+        return { ok: false, error: "cross_agent_file_id" };
+    }
+    let real;
+    try {
+        real = realpathSync(record.stagedPath);
+    }
+    catch {
+        return { ok: false, error: "file_missing" };
+    }
+    // Compare canonical-to-canonical: realpath BOTH sides. The staging root is realpath'd too so
+    // a symlinked $PASEO_HOME (e.g. macOS /var → /private/var) doesn't make a legitimately-staged
+    // file look like an escape. Containment is still strict — a symlink inside the dir whose
+    // target lives elsewhere resolves outside `realRoot` and is rejected. A root that cannot be
+    // resolved (never created) fails closed as an escape.
+    let realRoot;
+    try {
+        realRoot = realpathSync(path.resolve(paseoHome, "uploads", agentId));
+    }
+    catch {
+        return { ok: false, error: "staging_path_escape" };
+    }
+    if (!real.startsWith(realRoot + path.sep)) {
+        return { ok: false, error: "staging_path_escape" };
+    }
+    return { ok: true, path: real };
+}
+//# sourceMappingURL=file-attachment-validation.js.map

package/dist/server/server/uploads/staging-service.d.ts

@@ -0,0 +1,91 @@
+import { type WriteStream } from "node:fs";
+import type { z } from "zod";
+import { FileBeginMetadataSchema } from "@hyperdrive.bot/fleet-protocol/binary-frames/index";
+import type { FileUploadErrorCode } from "../messages.js";
+export type FileBeginMetadata = z.infer<typeof FileBeginMetadataSchema>;
+/**
+ * Default per-file upload size cap: 100 MB.
+ *
+ * Single source of the cap literal — the `session.ts` begin/chunk handlers consume the
+ * RESOLVED cap via `StagingService.maxFileSizeBytes`, never this constant directly, so the
+ * "100 * 1024 * 1024" literal lives only here.
+ */
+export declare const DEFAULT_MAX_UPLOAD_BYTES: number;
+export interface StagingBeginArgs {
+    agentId: string;
+    uploadId: string;
+    requestId: string;
+    /**
+     * Client-declared original filename, if any. Optional because the Epic-1
+     * `files.upload.begin.request` schema carries no filename field today — when absent the
+     * staged suffix falls back to `upload{ext}`. NEVER participates in the path except through
+     * `sanitizeUploadFilename`.
+     */
+    fileName?: string;
+    metadata: FileBeginMetadata;
+}
+/**
+ * Result of opening a disk-backed staging target for an inbound upload.
+ * On success it hands back a streamed write target (never an in-memory buffer);
+ * on rejection it carries the protocol error code so the caller can abort.
+ */
+export type StagingBeginResult = {
+    accepted: true;
+    writeStream: WriteStream;
+    stagedPath: string;
+    fileId: string;
+} | {
+    accepted: false;
+    error: FileUploadErrorCode;
+};
+export interface StagingService {
+    /**
+     * Resolved per-file upload size cap in bytes (config override or `DEFAULT_MAX_UPLOAD_BYTES`).
+     * Single source for the `session.ts` declared-size early reject and the mid-stream
+     * cumulative-bytes abort — neither re-declares the cap literal.
+     */
+    readonly maxFileSizeBytes: number;
+    /**
+     * Open a streamed write target for an inbound upload.
+     *
+     * Owns sanitization + server-side path construction + containment assertion + stream open
+     * ONLY. It does NOT enforce the size cap — the declared-size early reject lives in the
+     * `session.ts` begin handler so it can refuse before registering the transfer / opening a
+     * stream, and the mid-stream cumulative abort lives in the `session.ts` chunk handler.
+     * `beginUpload` is only reached after the early-reject gate passes.
+     *
+     * @param args - agent/upload/request identity, optional client filename, declared metadata
+     * @returns an accepted result carrying the write stream + staged path + fileId,
+     *          or a rejected result carrying `"write_failed"` (containment / fs failure).
+     */
+    beginUpload(args: StagingBeginArgs): Promise<StagingBeginResult>;
+}
+/**
+ * Map a small set of common mimes to a file extension for the no-filename fallback.
+ * Exhaustive coverage is NOT a goal — the uuid prefix already guarantees uniqueness.
+ */
+export declare function extFromMime(mime: string): string;
+/**
+ * Sanitize a raw client filename into a safe staging suffix. Pure (no I/O), so it is
+ * unit-tested directly against adversarial inputs. Rules applied in order:
+ *
+ *   (a) Unicode-normalize to NFC
+ *   (b) strip path separators `/` and `\`
+ *   (c) strip ASCII control chars `0x00`-`0x1F` and `0x7F` (NUL included)
+ *   (d) strip leading dots so the result is never `.`, `..`, or `.`-prefixed-only
+ *   (e) replace any remaining character not in `[A-Za-z0-9._-]` with `_`
+ *   (f) cap to <= 128 bytes, truncating the base and preserving a trailing extension
+ *   (g) if the result is empty, return the literal `"file"`
+ */
+export declare function sanitizeUploadFilename(rawName: string): string;
+/**
+ * Real staging service (story 2.2 — replaces the 2.1 stub).
+ *
+ * Stages each upload at `${paseoHome}/uploads/${agentId}/${uuid}-${sanitizedFilename}` via a
+ * real `fs.WriteStream` (never buffering). The raw client filename participates in the path
+ * ONLY through `sanitizeUploadFilename`, and a defense-in-depth containment assert guarantees
+ * the resolved path can never escape the agent staging dir. The size cap is resolved ONCE
+ * here and exposed via `maxFileSizeBytes` for the `session.ts` cap seams.
+ */
+export declare function createStagingService(paseoHome: string): StagingService;
+//# sourceMappingURL=staging-service.d.ts.map

package/dist/server/server/uploads/staging-service.js

@@ -0,0 +1,144 @@
+import { createWriteStream } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import * as path from "node:path";
+import { loadPersistedConfig } from "../persisted-config.js";
+/**
+ * Default per-file upload size cap: 100 MB.
+ *
+ * Single source of the cap literal — the `session.ts` begin/chunk handlers consume the
+ * RESOLVED cap via `StagingService.maxFileSizeBytes`, never this constant directly, so the
+ * "100 * 1024 * 1024" literal lives only here.
+ */
+export const DEFAULT_MAX_UPLOAD_BYTES = 100 * 1024 * 1024;
+/** Max staged filename length in bytes (the uuid prefix guarantees uniqueness regardless). */
+const MAX_FILENAME_BYTES = 128;
+const MIME_EXTENSIONS = {
+    "image/png": ".png",
+    "image/jpeg": ".jpg",
+    "application/pdf": ".pdf",
+    "text/plain": ".txt",
+};
+/**
+ * Map a small set of common mimes to a file extension for the no-filename fallback.
+ * Exhaustive coverage is NOT a goal — the uuid prefix already guarantees uniqueness.
+ */
+export function extFromMime(mime) {
+    return MIME_EXTENSIONS[mime] ?? ".bin";
+}
+/**
+ * Truncate a filename to at most `maxBytes` UTF-8 bytes, preserving a trailing extension
+ * where present. The base name is truncated on character boundaries so the result is always
+ * valid UTF-8.
+ */
+function capFilenameBytes(name, maxBytes) {
+    if (Buffer.byteLength(name, "utf8") <= maxBytes) {
+        return name;
+    }
+    const ext = path.extname(name);
+    const extBytes = Buffer.byteLength(ext, "utf8");
+    const base = ext.length > 0 ? name.slice(0, name.length - ext.length) : name;
+    const budget = Math.max(0, maxBytes - extBytes);
+    let truncated = "";
+    let bytes = 0;
+    for (const ch of base) {
+        const chBytes = Buffer.byteLength(ch, "utf8");
+        if (bytes + chBytes > budget) {
+            break;
+        }
+        truncated += ch;
+        bytes += chBytes;
+    }
+    return truncated + ext;
+}
+/**
+ * Sanitize a raw client filename into a safe staging suffix. Pure (no I/O), so it is
+ * unit-tested directly against adversarial inputs. Rules applied in order:
+ *
+ *   (a) Unicode-normalize to NFC
+ *   (b) strip path separators `/` and `\`
+ *   (c) strip ASCII control chars `0x00`-`0x1F` and `0x7F` (NUL included)
+ *   (d) strip leading dots so the result is never `.`, `..`, or `.`-prefixed-only
+ *   (e) replace any remaining character not in `[A-Za-z0-9._-]` with `_`
+ *   (f) cap to <= 128 bytes, truncating the base and preserving a trailing extension
+ *   (g) if the result is empty, return the literal `"file"`
+ */
+export function sanitizeUploadFilename(rawName) {
+    let name = rawName.normalize("NFC");
+    name = name.replace(/[/\\]/g, "");
+    // Strip ASCII control chars 0x00-0x1F and 0x7F (NUL included). Done by code-point
+    // filter (not a regex) so the source carries no control chars and avoids
+    // no-control-regex.
+    name = [...name]
+        .filter((ch) => {
+        const code = ch.codePointAt(0) ?? 0;
+        return !(code <= 0x1f || code === 0x7f);
+    })
+        .join("");
+    name = name.replace(/^\.+/, "");
+    name = name.replace(/[^A-Za-z0-9._-]/g, "_");
+    name = capFilenameBytes(name, MAX_FILENAME_BYTES);
+    if (name.length === 0) {
+        return "file";
+    }
+    return name;
+}
+/**
+ * Resolve the per-file upload size cap from persisted config, falling back to the default.
+ * Reads `daemon.uploads.maxFileSizeBytes` and only honors it when it is a positive integer;
+ * absent / zero / negative values yield `DEFAULT_MAX_UPLOAD_BYTES` (the positive-int guard).
+ */
+function resolveMaxUploadBytes(paseoHome) {
+    const configured = loadPersistedConfig(paseoHome).daemon?.uploads?.maxFileSizeBytes;
+    if (typeof configured === "number" && Number.isInteger(configured) && configured > 0) {
+        return configured;
+    }
+    return DEFAULT_MAX_UPLOAD_BYTES;
+}
+/**
+ * Real staging service (story 2.2 — replaces the 2.1 stub).
+ *
+ * Stages each upload at `${paseoHome}/uploads/${agentId}/${uuid}-${sanitizedFilename}` via a
+ * real `fs.WriteStream` (never buffering). The raw client filename participates in the path
+ * ONLY through `sanitizeUploadFilename`, and a defense-in-depth containment assert guarantees
+ * the resolved path can never escape the agent staging dir. The size cap is resolved ONCE
+ * here and exposed via `maxFileSizeBytes` for the `session.ts` cap seams.
+ */
+export function createStagingService(paseoHome) {
+    const maxFileSizeBytes = resolveMaxUploadBytes(paseoHome);
+    return {
+        maxFileSizeBytes,
+        async beginUpload(args) {
+            const { agentId, fileName, metadata } = args;
+            const suffix = sanitizeUploadFilename(fileName ?? `upload${extFromMime(metadata.mime)}`);
+            const stagedPath = path.join(paseoHome, "uploads", agentId, `${randomUUID()}-${suffix}`);
+            // Containment assert (defense-in-depth): the uuid prefix + sanitization make escape
+            // unreachable in practice, but the assert is acceptance-gating — no stream is opened
+            // unless the resolved path is strictly inside the agent staging dir.
+            const agentDir = path.resolve(paseoHome, "uploads", agentId);
+            if (!path.resolve(stagedPath).startsWith(agentDir + path.sep)) {
+                return { accepted: false, error: "write_failed" };
+            }
+            try {
+                await mkdir(path.dirname(stagedPath), { recursive: true });
+                const writeStream = createWriteStream(stagedPath);
+                // `createWriteStream` opens the fd ASYNCHRONOUSLY. Wait for the file to
+                // actually exist on disk before handing the stream back, otherwise:
+                //   - a chunk written immediately after begin races the open (the staged
+                //     file isn't on disk yet), and
+                //   - an abort's `rm` can run before the open completes, deleting nothing
+                //     and then the late open re-creates the partial AFTER cleanup.
+                // Awaiting `open` makes begin/chunk/abort observe a real on-disk file.
+                await new Promise((resolve, reject) => {
+                    writeStream.once("open", () => resolve());
+                    writeStream.once("error", reject);
+                });
+                return { accepted: true, writeStream, stagedPath, fileId: randomUUID() };
+            }
+            catch {
+                return { accepted: false, error: "write_failed" };
+            }
+        },
+    };
+}
+//# sourceMappingURL=staging-service.js.map

package/dist/server/server/utils/diff-highlighter.d.ts

@@ -0,0 +1,57 @@
+import { type HighlightToken } from "@hyperdrive.bot/fleet-highlight";
+export interface DiffLine {
+    type: "add" | "remove" | "context" | "header";
+    content: string;
+    tokens?: HighlightToken[];
+}
+export interface DiffHunk {
+    oldStart: number;
+    oldCount: number;
+    newStart: number;
+    newCount: number;
+    lines: DiffLine[];
+}
+export interface ParsedDiffFile {
+    path: string;
+    isNew: boolean;
+    isDeleted: boolean;
+    additions: number;
+    deletions: number;
+    hunks: DiffHunk[];
+    status?: "ok" | "too_large" | "binary";
+}
+interface HighlightDiffWithFileContentOptions {
+    oldFileContent?: string | null;
+    newFileContent?: string | null;
+}
+interface ParseAndHighlightDiffOptions {
+    getOldFileContent?: (file: ParsedDiffFile) => Promise<string | null>;
+    getNewFileContent?: (file: ParsedDiffFile) => Promise<string | null>;
+}
+export declare function parseDiff(diffText: string): ParsedDiffFile[];
+/**
+ * Reconstruct the "new" version of a file from diff hunks.
+ * Returns a map of new line numbers to their content.
+ */
+export declare function reconstructNewFile(hunks: DiffHunk[]): Map<number, string>;
+/**
+ * Reconstruct the "old" version of a file from diff hunks.
+ * Returns a map of old line numbers to their content.
+ */
+export declare function reconstructOldFile(hunks: DiffHunk[]): Map<number, string>;
+/**
+ * Apply syntax highlighting to diff hunks using reconstructed file content.
+ * This is the fallback when actual file content is not available.
+ */
+export declare function highlightDiffFromHunks(file: ParsedDiffFile): ParsedDiffFile;
+/**
+ * Apply syntax highlighting to diff hunks using actual file content.
+ * This provides better context for the parser.
+ */
+export declare function highlightDiffWithFileContent(file: ParsedDiffFile, cwd: string, options?: HighlightDiffWithFileContentOptions): Promise<ParsedDiffFile>;
+/**
+ * Parse and highlight a complete diff, using actual file content when available.
+ */
+export declare function parseAndHighlightDiff(diffText: string, cwd: string, options?: ParseAndHighlightDiffOptions): Promise<ParsedDiffFile[]>;
+export type { HighlightToken };
+//# sourceMappingURL=diff-highlighter.d.ts.map