@peakflo/agent-harness 0.2.3 → 0.2.4-rc.2

package/dist/runtime/space-files.d.ts

@@ -0,0 +1,82 @@
+import type { LeasedSpaceFiles } from '../types';
+export declare const SPACE_FILES_DIR = "space-files";
+export declare const SPACE_FILES_MANIFEST_NAME = "MANIFEST.md";
+export declare const SPACE_FILES_MANIFEST_PATH = "space-files/MANIFEST.md";
+export declare const OUTPUTS_DIR = "outputs";
+export declare const DOWNLOADS_DIR = "downloads";
+/**
+ * Harness-side ceilings. They MIRROR the control plane's
+ * `SPACE_FILE_MAX_BYTES` and `SPACE_FILES_MAX_TOTAL_BYTES`. The effective limit
+ * is the SMALLER of the lease's value and this one, so an old control plane can
+ * never raise what this harness will write.
+ */
+export declare const SPACE_FILE_MAX_BYTES: number;
+export declare const SPACE_FILES_MAX_TOTAL_BYTES: number;
+/** Per-file download wall clock. */
+export declare const SPACE_FILE_DOWNLOAD_TIMEOUT_MS = 120000;
+/** Replace control characters and separators with `_`, one character at a time. */
+export declare function replaceControlCharacters(raw: string): string;
+/**
+ * `space-files/<segment>` or `space-files/<folder>/<segment>`, where a segment
+ * has no separator, no control character and is not `.`/`..` or dot-prefixed.
+ */
+export interface SpaceFilePresent {
+    path: string;
+    sizeBytes: number;
+    mimeType: string | null;
+}
+export interface SpaceFileNotDownloaded {
+    path: string;
+    name: string;
+    sizeBytes: number;
+    reason: 'too_large' | 'workspace_limit';
+}
+export interface SpaceFilesSyncResult {
+    /** Everything now on disk under `space-files/` that the manifest lists. */
+    present: SpaceFilePresent[];
+    /** Downloaded this turn. */
+    downloaded: string[];
+    /** Already present and unchanged; not fetched again. */
+    kept: string[];
+    /** Deleted this turn: no longer in the manifest, or changed and then failed. */
+    removed: string[];
+    /** Listed, but could not be fetched. Logged, and left out of MANIFEST.md. */
+    failed: Array<{
+        path: string;
+        reason: string;
+    }>;
+    /** Listed in MANIFEST.md with the reason, and no download attempted. */
+    notDownloaded: SpaceFileNotDownloaded[];
+}
+export interface SpaceFilesSyncOptions {
+    fetchImpl?: typeof fetch;
+    logger: Pick<Console, 'log' | 'warn'>;
+    downloadTimeoutMs?: number;
+}
+/** A path the harness will write to, or null. The manifest is untrusted input. */
+export declare function isSafeSpaceFilePath(path: unknown): path is string;
+/**
+ * Stream a signed URL into `dest`, refusing anything over `maxBytes`. The
+ * manifest's size is the authority: a body of a different length is a file that
+ * changed under us, and it is not kept.
+ */
+export declare function downloadTo(url: string, dest: string, options: {
+    maxBytes: number;
+    timeoutMs: number;
+    fetchImpl: typeof fetch;
+}): Promise<void>;
+/**
+ * `space-files/MANIFEST.md`. Written every turn. It names only present files as
+ * readable; anything else is listed under "Not downloaded" with the reason.
+ */
+export declare function renderSpaceFilesManifest(result: SpaceFilesSyncResult): string;
+/**
+ * Make the workspace's `space-files/` match `manifest`. Returns what happened.
+ *
+ * `manifest` undefined means the turn has no Space files at all. The same
+ * cleanup runs, so a chat that moved to a Space with no files does not keep the
+ * previous Space's copies on disk.
+ */
+export declare function syncSpaceFiles(manifest: LeasedSpaceFiles | undefined, workspaceDir: string, options: SpaceFilesSyncOptions): Promise<SpaceFilesSyncResult>;
+/** Whether this workspace has a sync record from an earlier turn. */
+export declare function hasSpaceFilesState(workspaceDir: string): Promise<boolean>;

package/dist/runtime/space-files.js

@@ -0,0 +1,422 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SPACE_FILE_DOWNLOAD_TIMEOUT_MS = exports.SPACE_FILES_MAX_TOTAL_BYTES = exports.SPACE_FILE_MAX_BYTES = exports.DOWNLOADS_DIR = exports.OUTPUTS_DIR = exports.SPACE_FILES_MANIFEST_PATH = exports.SPACE_FILES_MANIFEST_NAME = exports.SPACE_FILES_DIR = void 0;
+exports.replaceControlCharacters = replaceControlCharacters;
+exports.isSafeSpaceFilePath = isSafeSpaceFilePath;
+exports.downloadTo = downloadTo;
+exports.renderSpaceFilesManifest = renderSpaceFilesManifest;
+exports.syncSpaceFiles = syncSpaceFiles;
+exports.hasSpaceFilesState = hasSpaceFilesState;
+/**
+ * SPACE FILES → THE WORKSPACE, READ-ONLY (P9).
+ *
+ * The lease carries `session.spaceFiles`: the files of the chat's Space and its
+ * ancestors that the speaker may read, each with a short-lived signed URL. This
+ * module makes the workspace match that list on EVERY turn:
+ *
+ *   - a file that is new, or changed (its `updatedAt` or size moved), is
+ *     downloaded to a temp file and renamed into place;
+ *   - a file that is already there and unchanged is left alone;
+ *   - a file no longer in the list is deleted, and so is anything else under
+ *     `space-files/` that is not in the list (a stale mirror cannot survive);
+ *   - every file is made read-only (0444). The agent reads these; new or
+ *     changed work goes to `outputs/`.
+ *
+ * `space-files/MANIFEST.md` lists ONLY what is actually present, plus the files
+ * that were skipped for size, so the model never plans around a file it cannot
+ * open. A stopped or resumed sandbox re-syncs on its next turn, because the
+ * check is against the disk, not against a memory of the last turn.
+ *
+ * NEVER FATAL. A file that fails is logged by path and left out; the turn runs
+ * with the rest. URLs are never logged, and error text is scrubbed of them.
+ *
+ * THE LEASE IS INPUT. The manifest crosses the wire, so every path is checked
+ * against the expected shape again here, and anything that does not fit is
+ * dropped. A path can never leave `space-files/`.
+ */
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const node_stream_1 = require("node:stream");
+const promises_2 = require("node:stream/promises");
+const attachments_1 = require("./attachments");
+exports.SPACE_FILES_DIR = 'space-files';
+exports.SPACE_FILES_MANIFEST_NAME = 'MANIFEST.md';
+exports.SPACE_FILES_MANIFEST_PATH = `${exports.SPACE_FILES_DIR}/${exports.SPACE_FILES_MANIFEST_NAME}`;
+exports.OUTPUTS_DIR = 'outputs';
+exports.DOWNLOADS_DIR = 'downloads';
+/** Hidden, at the workspace root. Records what this workspace was last synced with. */
+const STATE_FILE = '.pf-space-files.json';
+const TEMP_PREFIX = '.tmp-';
+/**
+ * Harness-side ceilings. They MIRROR the control plane's
+ * `SPACE_FILE_MAX_BYTES` and `SPACE_FILES_MAX_TOTAL_BYTES`. The effective limit
+ * is the SMALLER of the lease's value and this one, so an old control plane can
+ * never raise what this harness will write.
+ */
+exports.SPACE_FILE_MAX_BYTES = 50 * 1024 * 1024;
+exports.SPACE_FILES_MAX_TOTAL_BYTES = 200 * 1024 * 1024;
+/** Per-file download wall clock. */
+exports.SPACE_FILE_DOWNLOAD_TIMEOUT_MS = 120_000;
+/** Replace control characters and separators with `_`, one character at a time. */
+function replaceControlCharacters(raw) {
+    let out = '';
+    for (const ch of raw) {
+        const code = ch.codePointAt(0) ?? 0;
+        out += code < 32 || code === 127 || '\\/'.includes(ch) ? '_' : ch;
+    }
+    return out;
+}
+/** One path segment: 1 to 200 characters, with no separator and no control character. */
+function isPlainSegment(segment) {
+    return (segment.length >= 1 &&
+        segment.length <= 200 &&
+        replaceControlCharacters(segment) === segment);
+}
+/** A path the harness will write to, or null. The manifest is untrusted input. */
+function isSafeSpaceFilePath(path) {
+    if (typeof path !== 'string' || path.length > 512)
+        return false;
+    const parts = path.split('/');
+    if (parts[0] !== exports.SPACE_FILES_DIR)
+        return false;
+    if (parts.length < 2 || parts.length > 3)
+        return false;
+    if (path === exports.SPACE_FILES_MANIFEST_PATH)
+        return false;
+    return parts
+        .slice(1)
+        .every((segment) => isPlainSegment(segment) &&
+        segment !== '.' &&
+        segment !== '..' &&
+        !segment.startsWith('.') &&
+        segment.trim() === segment);
+}
+function scrub(message) {
+    return message.replace(/https?:\/\/\S+/gi, '<url>').slice(0, 300);
+}
+async function sizeOf(file) {
+    try {
+        const info = await (0, promises_1.stat)(file);
+        return info.isFile() ? info.size : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function readState(root) {
+    try {
+        const parsed = JSON.parse(await (0, promises_1.readFile)((0, node_path_1.join)(root, STATE_FILE), 'utf8'));
+        const out = {};
+        for (const [path, entry] of Object.entries(parsed.files ?? {})) {
+            if (typeof entry?.key === 'string' && typeof entry.sizeBytes === 'number')
+                out[path] = { key: entry.key, sizeBytes: entry.sizeBytes };
+        }
+        return out;
+    }
+    catch {
+        return {};
+    }
+}
+async function writeAtomic(file, contents) {
+    const tmp = (0, node_path_1.join)((0, node_path_1.dirname)(file), `${TEMP_PREFIX}${(0, node_crypto_1.randomUUID)()}`);
+    await (0, promises_1.writeFile)(tmp, contents, { mode: 0o644 });
+    await (0, promises_1.rename)(tmp, file);
+}
+/** The change key. A new `updatedAt` or a new size is a changed file. */
+function changeKey(file) {
+    return `${file.fileId}:${file.updatedAt ?? ''}:${file.sizeBytes}`;
+}
+/**
+ * Stream a signed URL into `dest`, refusing anything over `maxBytes`. The
+ * manifest's size is the authority: a body of a different length is a file that
+ * changed under us, and it is not kept.
+ */
+async function downloadTo(url, dest, options) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), options.timeoutMs);
+    try {
+        // A signed URL does not redirect. A redirect would be a host we did not sign for.
+        const response = await options.fetchImpl(url, {
+            signal: controller.signal,
+            redirect: 'error'
+        });
+        if (!response.ok)
+            throw new Error(`storage answered HTTP ${response.status}`);
+        if (!response.body)
+            throw new Error('storage returned an empty body');
+        const declared = Number(response.headers.get('content-length'));
+        if (Number.isFinite(declared) && declared > options.maxBytes)
+            throw new Error('storage body is larger than the manifest size');
+        let received = 0;
+        const meter = new node_stream_1.Transform({
+            transform(chunk, _encoding, callback) {
+                received += chunk.length;
+                if (received > options.maxBytes) {
+                    callback(new Error('storage body is larger than the manifest size'));
+                    return;
+                }
+                callback(null, chunk);
+            }
+        });
+        await (0, promises_2.pipeline)(node_stream_1.Readable.fromWeb(response.body), meter, (0, node_fs_1.createWriteStream)(dest, { flags: 'wx' }));
+        if (received !== options.maxBytes)
+            throw new Error(`size mismatch: manifest ${options.maxBytes}, received ${received}`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Every regular file under `space-files/`, as workspace-relative paths. */
+async function listManagedFiles(root) {
+    const out = [];
+    const walk = async (relative, depth) => {
+        if (depth > 3)
+            return;
+        let entries;
+        try {
+            entries = await (0, promises_1.readdir)((0, node_path_1.join)(root, relative), { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const next = `${relative}/${entry.name}`;
+            if (entry.isDirectory())
+                await walk(next, depth + 1);
+            else if (entry.isFile())
+                out.push(next);
+        }
+    };
+    await walk(exports.SPACE_FILES_DIR, 0);
+    return out;
+}
+/** Remove now-empty folders under `space-files/`, deepest first. Never the root. */
+async function pruneEmptyFolders(root) {
+    const walk = async (relative, depth) => {
+        if (depth > 3)
+            return;
+        let entries;
+        try {
+            entries = await (0, promises_1.readdir)((0, node_path_1.join)(root, relative), { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.isDirectory())
+                await walk(`${relative}/${entry.name}`, depth + 1);
+        }
+        if (relative !== exports.SPACE_FILES_DIR) {
+            try {
+                await (0, promises_1.rmdir)((0, node_path_1.join)(root, relative));
+            }
+            catch {
+                // Not empty, or already gone. Either is fine.
+            }
+        }
+    };
+    await walk(exports.SPACE_FILES_DIR, 0);
+}
+function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+/** A file name shown in Markdown. Backticks would end the code span. */
+function codeSpan(text) {
+    return `\`${text.replace(/`/g, "'")}\``;
+}
+/**
+ * `space-files/MANIFEST.md`. Written every turn. It names only present files as
+ * readable; anything else is listed under "Not downloaded" with the reason.
+ */
+function renderSpaceFilesManifest(result) {
+    const lines = [
+        '# Space files',
+        '',
+        "Read-only copies of the files in this chat's Space and its parent Spaces.",
+        'Changes made here are discarded at the next turn. Write new or changed files to `outputs/`.',
+        '',
+        `## Files (${result.present.length})`,
+        ''
+    ];
+    if (!result.present.length) {
+        lines.push('No files are present.', '');
+    }
+    else {
+        for (const file of [...result.present].sort((a, b) => a.path.localeCompare(b.path))) {
+            lines.push(`- ${codeSpan(file.path)}: ${formatBytes(file.sizeBytes)}, ${file.mimeType ?? 'unknown type'}`);
+        }
+        lines.push('');
+    }
+    if (result.notDownloaded.length) {
+        lines.push('## Not downloaded', '');
+        for (const file of result.notDownloaded) {
+            const why = file.reason === 'too_large'
+                ? `not downloaded (too large, over ${formatBytes(exports.SPACE_FILE_MAX_BYTES)})`
+                : 'not downloaded (workspace size limit reached)';
+            lines.push(`- ${codeSpan(file.path)}: ${formatBytes(file.sizeBytes)}, ${why}. Use knowledge_file_download to fetch it into downloads/.`);
+        }
+        lines.push('');
+    }
+    return `${lines.join('\n')}\n`;
+}
+async function writeManifest(root, result) {
+    const file = (0, node_path_1.join)(root, exports.SPACE_FILES_MANIFEST_PATH);
+    await (0, promises_1.rm)(file, { force: true });
+    const tmp = (0, node_path_1.join)(root, exports.SPACE_FILES_DIR, `${TEMP_PREFIX}${(0, node_crypto_1.randomUUID)()}`);
+    await (0, promises_1.writeFile)(tmp, renderSpaceFilesManifest(result), { mode: 0o444 });
+    await (0, promises_1.rename)(tmp, file);
+    await (0, promises_1.chmod)(file, 0o444);
+}
+/**
+ * Make the workspace's `space-files/` match `manifest`. Returns what happened.
+ *
+ * `manifest` undefined means the turn has no Space files at all. The same
+ * cleanup runs, so a chat that moved to a Space with no files does not keep the
+ * previous Space's copies on disk.
+ */
+async function syncSpaceFiles(manifest, workspaceDir, options) {
+    const root = (0, node_path_1.resolve)(workspaceDir);
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const { logger } = options;
+    const timeoutMs = options.downloadTimeoutMs ?? exports.SPACE_FILE_DOWNLOAD_TIMEOUT_MS;
+    const maxFile = Math.min(manifest?.limits?.maxFileBytes ?? exports.SPACE_FILE_MAX_BYTES, exports.SPACE_FILE_MAX_BYTES);
+    const maxTotal = Math.min(manifest?.limits?.maxTotalBytes ?? exports.SPACE_FILES_MAX_TOTAL_BYTES, exports.SPACE_FILES_MAX_TOTAL_BYTES);
+    const result = {
+        present: [],
+        downloaded: [],
+        kept: [],
+        removed: [],
+        failed: [],
+        notDownloaded: []
+    };
+    await (0, promises_1.mkdir)((0, node_path_1.join)(root, exports.SPACE_FILES_DIR), { recursive: true });
+    await (0, promises_1.mkdir)((0, node_path_1.join)(root, exports.OUTPUTS_DIR), { recursive: true });
+    // The mirror and its state file are not work product. Keep them out of a repo's `git status`.
+    await (0, attachments_1.excludePatternFromGit)(root, `/${exports.SPACE_FILES_DIR}/`, logger);
+    await (0, attachments_1.excludePatternFromGit)(root, `/${STATE_FILE}`, logger);
+    // 1. Validate the lease's list. Anything that does not fit is dropped here.
+    const desired = new Map();
+    let plannedBytes = 0;
+    for (const file of manifest?.files ?? []) {
+        if (!file || !isSafeSpaceFilePath(file.path) || desired.has(file.path)) {
+            logger.warn('[space-files] manifest entry dropped: unsafe or duplicate path');
+            continue;
+        }
+        if (typeof file.url !== 'string' || !/^https?:\/\//i.test(file.url)) {
+            logger.warn(`[space-files] ${file.path} dropped: URL is not fetchable`);
+            continue;
+        }
+        const size = Number(file.sizeBytes);
+        if (!Number.isSafeInteger(size) || size < 0)
+            continue;
+        if (size > maxFile) {
+            result.notDownloaded.push({
+                path: file.path,
+                name: file.name,
+                sizeBytes: size,
+                reason: 'too_large'
+            });
+            continue;
+        }
+        if (plannedBytes + size > maxTotal) {
+            result.notDownloaded.push({
+                path: file.path,
+                name: file.name,
+                sizeBytes: size,
+                reason: 'workspace_limit'
+            });
+            continue;
+        }
+        plannedBytes += size;
+        desired.set(file.path, file);
+    }
+    for (const skipped of manifest?.skipped ?? []) {
+        if (!isSafeSpaceFilePath(skipped?.path))
+            continue;
+        if (desired.has(skipped.path))
+            continue;
+        result.notDownloaded.push({
+            path: skipped.path,
+            name: skipped.name,
+            sizeBytes: Number(skipped.sizeBytes) || 0,
+            reason: skipped.reason === 'too_large' ? 'too_large' : 'workspace_limit'
+        });
+    }
+    const state = await readState(root);
+    const nextState = {};
+    // 2. Bring each listed file to the listed state, one at a time.
+    for (const file of desired.values()) {
+        const dest = (0, node_path_1.join)(root, file.path);
+        const key = changeKey(file);
+        const onDisk = await sizeOf(dest);
+        if (state[file.path]?.key === key && onDisk === file.sizeBytes) {
+            result.kept.push(file.path);
+            nextState[file.path] = { key, sizeBytes: file.sizeBytes };
+            continue;
+        }
+        // The temp file sits in the mirror's root, not beside `dest`: a folder for
+        // an inherited Space may not exist yet, and a rename within one tree is atomic.
+        const tmp = (0, node_path_1.join)(root, exports.SPACE_FILES_DIR, `${TEMP_PREFIX}${(0, node_crypto_1.randomUUID)()}`);
+        try {
+            await downloadTo(file.url, tmp, {
+                maxBytes: file.sizeBytes,
+                timeoutMs,
+                fetchImpl
+            });
+            await (0, promises_1.chmod)(tmp, 0o444);
+            await (0, promises_1.mkdir)((0, node_path_1.dirname)(dest), { recursive: true });
+            // A same-named read-only file from the last turn is replaced by rename.
+            await (0, promises_1.rename)(tmp, dest);
+            result.downloaded.push(file.path);
+            nextState[file.path] = { key, sizeBytes: file.sizeBytes };
+        }
+        catch (error) {
+            await (0, promises_1.rm)(tmp, { force: true });
+            // A changed file that could not be fetched must not stay as stale content.
+            if (onDisk !== null) {
+                await (0, promises_1.rm)(dest, { force: true });
+                result.removed.push(file.path);
+            }
+            const reason = scrub(error instanceof Error ? error.message : String(error));
+            result.failed.push({ path: file.path, reason });
+            logger.warn(`[space-files] ${file.path} not synced: ${reason}`);
+        }
+    }
+    // 3. Delete everything under space-files/ that the list does not keep.
+    //    A leftover temp file from a crashed sync is not a Space file: it goes
+    //    quietly. Anything else the list does not keep is reported as removed.
+    const keep = new Set([...result.kept, ...result.downloaded]);
+    for (const relative of await listManagedFiles(root)) {
+        if (relative === exports.SPACE_FILES_MANIFEST_PATH || keep.has(relative))
+            continue;
+        const isTemp = (relative.split('/').pop() ?? '').startsWith(TEMP_PREFIX);
+        await (0, promises_1.rm)((0, node_path_1.join)(root, relative), { force: true });
+        if (!isTemp && !result.removed.includes(relative))
+            result.removed.push(relative);
+    }
+    await pruneEmptyFolders(root);
+    // 4. Record what is now present, so the next turn can tell a change from a copy.
+    for (const path of [...result.kept, ...result.downloaded]) {
+        const size = (await sizeOf((0, node_path_1.join)(root, path))) ?? 0;
+        result.present.push({
+            path,
+            sizeBytes: size,
+            mimeType: desired.get(path)?.mimeType ?? null
+        });
+    }
+    await writeAtomic((0, node_path_1.join)(root, STATE_FILE), `${JSON.stringify({ version: 1, files: nextState }, null, 2)}\n`);
+    // 5. The manifest: what is present, then what was skipped and why.
+    await writeManifest(root, result);
+    logger.log(`[space-files] synced ${result.present.length} file(s): ${result.downloaded.length} downloaded, ${result.kept.length} unchanged, ${result.removed.length} removed, ${result.failed.length} failed, ${result.notDownloaded.length} not downloaded`);
+    return result;
+}
+/** Whether this workspace has a sync record from an earlier turn. */
+async function hasSpaceFilesState(workspaceDir) {
+    return (await sizeOf((0, node_path_1.join)((0, node_path_1.resolve)(workspaceDir), STATE_FILE))) !== null;
+}

package/dist/types.d.ts

@@ -216,6 +216,13 @@ export interface RunnerCapabilities {
     maxConcurrentSessions: number;
     /** Free-form routing labels, e.g. ['eu-only', 'has-vpn']. */
     labels?: string[];
+    /**
+     * Named features this harness implements, so the control plane can gate
+     * behaviour on them. A harness that does not list a feature must be treated
+     * as not having it: `spaceFiles` means the harness syncs `space-files/` and
+     * serves `knowledge_files_list` / `knowledge_file_download`.
+     */
+    features?: string[];
 }
 export interface RunnerBackend {
     /** 'opencode' | 'claude-code' | 'codex' | 'acp' | ... — an open vocabulary. */
@@ -450,6 +457,11 @@ export interface LeasedSession {
     backendOwnerId?: string | null;
     workspace: LeasedWorkspace;
     limits: LeasedLimits;
+    /**
+     * The Space files manifest for this turn (P9). Absent for a turn with no
+     * Space, and for a control plane that predates the capability.
+     */
+    spaceFiles?: LeasedSpaceFiles;
 }
 export interface LeasedAgent {
     agentId: string;
@@ -467,6 +479,13 @@ export interface LeasedAgent {
     /** Always the skill's PUBLISHED content, never its draft. */
     skills: LeasedSkill[];
     mcpServers: LeasedMcpServer[];
+    /**
+     * Optional and additive. Absent means an older control plane, and the
+     * harness then applies no dev-server refusal.
+     */
+    devServerPolicy?: {
+        blockDevServers: boolean;
+    };
 }
 export interface LeasedModel {
     provider: string;
@@ -532,6 +551,67 @@ export interface LeasedAttachment {
     url: string;
     sizeBytes?: number;
 }
+/**
+ * The Space files manifest (P9). Present only when the runner advertised the
+ * `spaceFiles` capability. The control plane decides WHICH files; the harness
+ * decides WHERE they land and whether they are still there.
+ */
+export interface LeasedSpaceFiles {
+    limits: {
+        maxFileBytes: number;
+        maxTotalBytes: number;
+        urlTtlSeconds: number;
+    };
+    files: LeasedSpaceFile[];
+    /** Present in storage, not downloaded: too large, or over the workspace budget. */
+    skipped: LeasedSpaceFileSkip[];
+    /** More files exist than the manifest lists. */
+    truncated: boolean;
+}
+export interface LeasedSpaceFile {
+    fileId: string;
+    datastoreId: string;
+    spaceId: string;
+    spaceName: string;
+    /** Relative to the workspace, e.g. `space-files/Sales/q3.csv`. */
+    path: string;
+    name: string;
+    sizeBytes: number;
+    mimeType: string | null;
+    updatedAt: string | null;
+    /** Short-lived signed URL. Fetched by the harness and never logged. */
+    url: string;
+}
+export interface LeasedSpaceFileSkip {
+    fileId: string;
+    path: string;
+    name: string;
+    sizeBytes: number;
+    mimeType: string | null;
+    reason: 'too_large' | 'workspace_limit';
+}
+/** One knowledge file the agent may read: metadata only, never a URL or path. */
+export interface KnowledgeFileListing {
+    fileId: string;
+    datastoreId: string;
+    datastoreName: string;
+    name: string;
+    mimeType: string | null;
+    sizeBytes: number | null;
+    status: 'ready' | 'pending';
+}
+export interface KnowledgeFilesResponse {
+    files: KnowledgeFileListing[];
+    truncated: boolean;
+}
+export interface KnowledgeDownloadResponse {
+    name: string;
+    mimeType: string | null;
+    sizeBytes: number;
+    /** Short-lived. Fetched by the harness, never shown to the model or logged. */
+    url: string;
+    expiresInSeconds: number;
+}
 export interface LeasedWorkspace {
     /**
      * 'scratch' is a bare working directory and is the default — the product

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peakflo/agent-harness",
-  "version": "0.2.3",
+  "version": "0.2.4-rc.2",
   "description": "Headless Peakflo coding-agent harness. One codebase, three hosting modes: a Daytona cloud sandbox, a customer VM, and the 20x desktop.",
   "license": "MIT",
   "type": "commonjs",