feat: list generated deliverables in the slash file picker (#163)

## Summary
- merges durable uploads and generated outputs in the `/` project-file
picker
- inserts an unambiguous `/deliverables/<output-id>/<filename>`
reference for generated files
- restores only selected deliverables from checksum-verified R2 storage
before model execution
- keeps opening the picker metadata-only, so it does not start Daytona

## Architecture
The agent worker joins generated outputs to their owning run and project
under signed tenant context. The web picker consumes one discriminated
upload/deliverable catalog. When a generated reference is submitted, the
run validates project ownership plus R2 identity/checksum metadata and
materializes that exact object into the project workspace through the
leased ProjectSandbox.

## Decisions made
| Decision | Choice | Reason |
|---|---|---|
| Reference identity | Full output UUID in the project path | Duplicate
filenames remain exact and cross-project references fail closed |
| Restore timing | On submit, not on menu open | The slash menu remains
fast and never wakes a sandbox |
| Source of truth | Postgres metadata plus R2 bytes | Workspace files
can disappear across idle recovery without losing referability |
| Schema | Discriminated `upload` / `deliverable` entries | Existing
upload metadata stays precise while generated files expose only durable
fields |

## Edge cases handled
- duplicate deliverable filenames across runs
- stale, missing, cross-user, or cross-project output references
- R2 identity, MIME type, size, and checksum mismatches
- generated files missing from an idle or recreated workspace
- multiple references in one message, bounded to ten unique outputs
- generated source paths remain read-only through file mutation tools

## Verification
- `pnpm lint`
- `pnpm typecheck`
- `pnpm turbo build --force`
- `pnpm deadcode`
- `pnpm architecture:check`
- `pnpm turbo skills:build`

Production browser QA will be completed after merge and deployment
against the existing research project containing two durable PDF
deliverables.

Author: iamjr15

apps/agent-worker/README.md

@@ -33,6 +33,14 @@ existence before minting a one-hour HMAC capability; the public signed download
 streaming second hop. Expiring capabilities and internal R2 keys are never stored in transcripts or
 returned by artifact tools.
 
+The project file catalog merges uploaded-file metadata with the newest durable generated-output
+records without starting Daytona. Generated entries use an ID-backed
+`deliverables/<output-id>/<filename>` path, so duplicate names remain unambiguous. When a user
+actually references one, the run rechecks user/project ownership, validates the R2 object's exact
+identity and checksum metadata, and restores only that output to its deterministic workspace path
+before model execution. Opening the slash menu therefore stays cheap, while old Deliverables remain
+usable after sandbox idle stops or workspace-file loss.
+
 User uploads are durable project files rather than prompt text. The authenticated project-file
 route accepts one bounded raw file at a time, validates its filename, extension, UTF-8 or binary
 signature, and tenant/project write state, then derives deterministic file and version UUIDs from

apps/agent-worker/src/durable-objects/agent-run-artifacts.ts

@@ -15,11 +15,10 @@ import {
 } from "@cheatcode/observability";
 import type { ArtifactUploadInput, ArtifactUploadResult } from "@cheatcode/sandbox-contracts";
 import type { AgentRunId, ProjectId, ThreadId, UserId } from "@cheatcode/types";
-import { ArtifactKindSchema } from "@cheatcode/types/artifacts";
+import { ArtifactKindSchema, GENERATED_OUTPUT_MAX_BYTES } from "@cheatcode/types/artifacts";
 import { closeDatabaseBestEffort } from "./db-close";
 
 const ARTIFACT_DIGEST_DOMAIN = "cheatcode:artifact-upload:v2";
-const MAX_ARTIFACT_BYTES = 32 * 1024 * 1024;
 const MAX_CONTENT_TYPE_LENGTH = 255;
 const VALID_CONTENT_TYPE = /^[a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*$/iu;
 
@@ -291,8 +290,10 @@ function assertArtifactUpload(artifact: ArtifactUploadInput): void {
   if (!(artifact.data instanceof Uint8Array)) {
     throw invalidArtifact("Artifact data must be binary");
   }
-  if (artifact.data.byteLength === 0 || artifact.data.byteLength > MAX_ARTIFACT_BYTES) {
-    throw invalidArtifact(`Artifact data must be between 1 byte and ${MAX_ARTIFACT_BYTES} bytes`);
+  if (artifact.data.byteLength === 0 || artifact.data.byteLength > GENERATED_OUTPUT_MAX_BYTES) {
+    throw invalidArtifact(
+      `Artifact data must be between 1 byte and ${GENERATED_OUTPUT_MAX_BYTES} bytes`,
+    );
   }
   if (!artifact.filename.trim() || artifact.filename.length > 255) {
     throw invalidArtifact("Artifact filename must be between 1 and 255 characters");

apps/agent-worker/src/durable-objects/agent-run-deliverables.ts

@@ -0,0 +1,152 @@
+import {
+  listReferencedProjectGeneratedOutputs,
+  type ReferencedProjectGeneratedOutputRecord,
+  withUserDb,
+} from "@cheatcode/db";
+import { APIError, type createLogger } from "@cheatcode/observability";
+import { toProjectId, toUserId } from "@cheatcode/types";
+import { ProjectDeliverableRelativePathSchema } from "@cheatcode/types/api";
+import { GENERATED_OUTPUT_MAX_BYTES } from "@cheatcode/types/artifacts";
+import type { AgentRunEnv } from "./agent-run-env";
+import type { StartRunInput } from "./agent-run-schemas";
+import type { ProjectSandbox } from "./project-sandbox";
+
+const DELIVERABLE_REFERENCE_PATTERN =
+  /(?:^|\s)(\/deliverables\/[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\/[a-z0-9._-]+)(?=\s|$)/gu;
+const MAX_REFERENCED_DELIVERABLES = 10;
+
+interface DeliverableReference {
+  filename: string;
+  outputId: string;
+}
+
+interface RestoreReferencedDeliverablesOptions {
+  env: AgentRunEnv;
+  input: StartRunInput;
+  logger: ReturnType<typeof createLogger>;
+  sandbox: DurableObjectStub<ProjectSandbox>;
+}
+
+/** Restores only explicitly referenced durable outputs into their deterministic project paths. */
+export async function restoreReferencedDeliverables(
+  options: RestoreReferencedDeliverablesOptions,
+): Promise<void> {
+  const references = parseDeliverableReferences(options.input.messageText);
+  if (references.length === 0) return;
+  const { projectId, workspaceSlug } = options.input;
+  if (!projectId || !workspaceSlug) throw referencedDeliverableNotFound();
+  const outputs = await loadReferencedOutputs(
+    options.env,
+    options.input.userId,
+    projectId,
+    references,
+  );
+  const byId = new Map(outputs.map((output) => [output.id, output]));
+  for (const reference of references) {
+    const output = byId.get(reference.outputId);
+    if (!output || output.filename !== reference.filename) throw referencedDeliverableNotFound();
+    const bytes = await readVerifiedOutput(options.env.R2_OUTPUTS, output);
+    await options.sandbox.restoreGeneratedOutput({
+      bytes,
+      filename: reference.filename,
+      outputId: reference.outputId,
+      projectId,
+      workspaceSlug,
+    });
+  }
+  options.logger.info("project_deliverables_restored", {
+    projectId,
+    restoredFileCount: references.length,
+  });
+}
+
+function parseDeliverableReferences(message: string): DeliverableReference[] {
+  const references = new Map<string, DeliverableReference>();
+  for (const match of message.matchAll(DELIVERABLE_REFERENCE_PATTERN)) {
+    const source = match[1];
+    if (!source) continue;
+    const parsed = ProjectDeliverableRelativePathSchema.safeParse(source.slice(1));
+    if (!parsed.success) continue;
+    const [, outputId, filename] = parsed.data.split("/");
+    if (!outputId || !filename) continue;
+    references.set(outputId, { filename, outputId });
+    if (references.size > MAX_REFERENCED_DELIVERABLES) {
+      throw new APIError(
+        422,
+        "request_body_invalid",
+        `Reference at most ${MAX_REFERENCED_DELIVERABLES} deliverables in one message.`,
+        { retriable: false },
+      );
+    }
+  }
+  return [...references.values()];
+}
+
+async function loadReferencedOutputs(
+  env: AgentRunEnv,
+  sourceUserId: string,
+  sourceProjectId: string,
+  references: readonly DeliverableReference[],
+): Promise<ReferencedProjectGeneratedOutputRecord[]> {
+  const userId = toUserId(sourceUserId);
+  return withUserDb(env, userId, async ({ transaction }) => {
+    return transaction((tx) =>
+      listReferencedProjectGeneratedOutputs(tx, {
+        outputIds: references.map((reference) => reference.outputId),
+        projectId: toProjectId(sourceProjectId),
+        userId,
+      }),
+    );
+  });
+}
+
+async function readVerifiedOutput(
+  bucket: R2Bucket,
+  output: ReferencedProjectGeneratedOutputRecord,
+): Promise<Uint8Array<ArrayBuffer>> {
+  const object = await bucket.get(output.r2Key);
+  const metadata = object?.customMetadata;
+  const checksum = object?.checksums.sha256;
+  if (
+    !object ||
+    object.key !== output.r2Key ||
+    object.size <= 0 ||
+    object.size > GENERATED_OUTPUT_MAX_BYTES ||
+    object.httpMetadata?.contentType !== output.mimeType ||
+    metadata?.["filename"] !== output.filename ||
+    metadata?.["outputId"] !== output.id ||
+    !metadata["contentSha256"] ||
+    !checksum ||
+    bytesToHex(new Uint8Array(checksum)) !== metadata["contentSha256"]
+  ) {
+    throw referencedDeliverableInvalid();
+  }
+  const bytes = new Uint8Array(await object.arrayBuffer()) as Uint8Array<ArrayBuffer>;
+  if (bytes.byteLength !== object.size) throw referencedDeliverableInvalid();
+  return bytes;
+}
+
+function bytesToHex(bytes: Uint8Array): string {
+  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+function referencedDeliverableNotFound(): APIError {
+  return new APIError(
+    404,
+    "resource_output_not_found",
+    "A referenced deliverable is unavailable.",
+    {
+      hint: "Choose the file again from the project file menu.",
+      retriable: false,
+    },
+  );
+}
+
+function referencedDeliverableInvalid(): APIError {
+  return new APIError(
+    409,
+    "conflict_state_invalid",
+    "A referenced deliverable could not be restored safely.",
+    { retriable: false },
+  );
+}

apps/agent-worker/src/durable-objects/agent-run-lifecycle.ts

@@ -1,6 +1,7 @@
 import { mastra } from "@cheatcode/agent-core";
 import { createLogger } from "@cheatcode/observability";
 import type { UIMessageChunk } from "ai";
+import { restoreReferencedDeliverables } from "./agent-run-deliverables";
 import type { AgentRunEnv } from "./agent-run-env";
 import { toAgentRunStreamError } from "./agent-run-errors";
 import { persistOrQueueAssistantMessage } from "./agent-run-message-persistence";
@@ -92,6 +93,12 @@ async function executeActiveRun(execution: RunExecution): Promise<void> {
     return;
   }
   await restoreRunProjectFiles(execution);
+  await restoreReferencedDeliverables({
+    env: deps.env,
+    input,
+    logger: execution.logger,
+    sandbox: execution.sandbox,
+  });
   const path = await deps.executeRunPath(
     input,
     execution.sandbox,

apps/agent-worker/src/durable-objects/project-sandbox-content-support.ts

@@ -9,7 +9,7 @@ import {
 export const PROJECT_ARCHIVE_MAX_BYTES = 512 * 1024 * 1024;
 export const PROJECT_ARCHIVE_MAX_FILES = 25_000;
 export const WORKSPACE_DIR = "/workspace";
-const MANAGED_PROJECT_UPLOAD_PATH = /^\/workspace\/[^/]+\/uploads(?:\/|$)/u;
+const MANAGED_PROJECT_SOURCE_PATH = /^\/workspace\/[^/]+\/(?:deliverables|uploads)(?:\/|$)/u;
 const PROJECT_WORKSPACE_ROOT_PATH = /^\/workspace\/[^/]+\/?$/u;
 
 export const PROJECT_ARCHIVE_SCRIPT = `
@@ -106,11 +106,11 @@ if archive_size > max_output_bytes:
 export { PROJECT_ARCHIVE_MAX_OUTPUT_BYTES };
 
 export function assertMutableWorkspacePath(path: string): void {
-  if (!MANAGED_PROJECT_UPLOAD_PATH.test(path)) {
+  if (!MANAGED_PROJECT_SOURCE_PATH.test(path)) {
     return;
   }
-  throw new APIError(403, "permission_access_denied", "Uploaded project files are read-only", {
-    hint: "Read the uploaded file or copy it to another project path before editing it.",
+  throw new APIError(403, "permission_access_denied", "Referenced project files are read-only", {
+    hint: "Read the source file or copy it to another project path before editing it.",
     retriable: false,
   });
 }

apps/agent-worker/src/durable-objects/project-sandbox-generated-outputs.ts

@@ -0,0 +1,36 @@
+import type { SandboxWriteFileResult } from "@cheatcode/sandbox-contracts";
+import { projectDeliverableRelativePath } from "@cheatcode/types/api";
+import { dirname } from "../sandbox-support";
+import { WORKSPACE_DIR } from "./project-sandbox-content-support";
+import {
+  type ProjectRestoreGeneratedOutputInput,
+  ProjectRestoreGeneratedOutputInputSchema,
+} from "./project-sandbox-runtime";
+import type { SandboxRuntime } from "./project-sandbox-runtime-handle";
+
+type GeneratedOutputRuntime = Pick<SandboxRuntime, "client" | "ensureSandbox">;
+
+export interface GeneratedOutputOps {
+  restoreGeneratedOutput: (
+    input: ProjectRestoreGeneratedOutputInput,
+  ) => Promise<SandboxWriteFileResult>;
+}
+
+export function createGeneratedOutputOps(runtime: GeneratedOutputRuntime): GeneratedOutputOps {
+  return {
+    restoreGeneratedOutput: (input) => restoreGeneratedOutput(runtime, input),
+  };
+}
+
+async function restoreGeneratedOutput(
+  runtime: GeneratedOutputRuntime,
+  input: ProjectRestoreGeneratedOutputInput,
+): Promise<SandboxWriteFileResult> {
+  const parsed = ProjectRestoreGeneratedOutputInputSchema.parse(input);
+  const relativePath = projectDeliverableRelativePath(parsed.outputId, parsed.filename);
+  const path = `${WORKSPACE_DIR}/${parsed.workspaceSlug}/${relativePath}`;
+  const id = await runtime.ensureSandbox();
+  await runtime.client().createFolder(id, dirname(path));
+  await runtime.client().uploadFile(id, path, parsed.bytes);
+  return { path, success: true };
+}

apps/agent-worker/src/durable-objects/project-sandbox-lease-policy.ts

@@ -31,6 +31,7 @@ const LEASE_POLICIES = {
   readFile: ["workspace", "path"], listUploadedFiles: ["sandbox"],
   uploadProjectFile: ["workspace", "workspace-slug"],
   restoreUploadedFiles: ["workspace", "workspace-slug"],
+  restoreGeneratedOutput: ["workspace", "workspace-slug"],
   writeFile: ["workspace", "path"], listFiles: ["workspace", "path"],
   searchFiles: ["workspace", "path"], deleteFile: ["workspace", "path"],
   getSignedPreviewUrl: ["sandbox"], exposeBrowserTakeover: ["sandbox"],

apps/agent-worker/src/durable-objects/project-sandbox-project-files.ts

@@ -4,11 +4,11 @@ import { APIError } from "@cheatcode/observability";
 import {
   PROJECT_FILE_MAX_CURRENT_FILES,
   type ProjectFile,
-  ProjectFileListSchema,
   ProjectFileRelativePathSchema,
   ProjectFileSchema,
   type ProjectFileUploadResponse,
   ProjectFileUploadResponseSchema,
+  ProjectUploadedFileListSchema,
 } from "@cheatcode/types/api";
 import { z } from "zod";
 import { sleep } from "../sandbox-support";
@@ -534,7 +534,7 @@ async function listProjectFileRecords(
     return parsed.success ? [parsed.data] : [];
   });
   files.sort((left, right) => left.path.localeCompare(right.path));
-  return ProjectFileListSchema.parse({ files });
+  return ProjectUploadedFileListSchema.parse({ files });
 }
 
 async function deleteStoragePrefix(runtime: FileRuntime, prefix: string): Promise<void> {

apps/agent-worker/src/durable-objects/project-sandbox-runtime.ts

@@ -1,7 +1,12 @@
 import { WorkspaceFilePathSchema, WorkspacePathSchema } from "@cheatcode/agent-core/tools/code";
 import { EnvironmentVariablesSchema } from "@cheatcode/sandbox-contracts";
 import { toProjectId } from "@cheatcode/types";
-import { PROJECT_FILE_MAX_BYTES, ProjectFileRelativePathSchema } from "@cheatcode/types/api";
+import {
+  PROJECT_FILE_MAX_BYTES,
+  ProjectDeliverableFilenameSchema,
+  ProjectFileRelativePathSchema,
+} from "@cheatcode/types/api";
+import { GENERATED_OUTPUT_MAX_BYTES, OutputIdSchema } from "@cheatcode/types/artifacts";
 import { z } from "zod";
 import { shellQuote } from "../sandbox-support";
 
@@ -107,6 +112,24 @@ export const ProjectRestoreUploadedFilesInputSchema = z
     "Workspace slug does not belong to the requested project.",
   );
 
+export const ProjectRestoreGeneratedOutputInputSchema = z
+  .strictObject({
+    bytes: z
+      .instanceof(Uint8Array)
+      .refine(
+        (value) => value.byteLength > 0 && value.byteLength <= GENERATED_OUTPUT_MAX_BYTES,
+        `Generated outputs must be between 1 byte and ${GENERATED_OUTPUT_MAX_BYTES} bytes.`,
+      ),
+    filename: ProjectDeliverableFilenameSchema,
+    outputId: OutputIdSchema,
+    projectId: z.string().uuid().toLowerCase().transform(toProjectId),
+    workspaceSlug: ProjectWorkspaceSlugSchema,
+  })
+  .refine(
+    (input) => input.workspaceSlug.endsWith(`-${input.projectId.toLowerCase()}`),
+    "Workspace slug does not belong to the requested project.",
+  );
+
 export const ProjectListFilesInputSchema = z.strictObject({
   path: WorkspacePathSchema,
   includeHidden: z.boolean().default(false),
@@ -222,6 +245,9 @@ export type ProjectListUploadedFilesInput = z.input<typeof ProjectListUploadedFi
 export type ProjectRestoreUploadedFilesInput = z.input<
   typeof ProjectRestoreUploadedFilesInputSchema
 >;
+export type ProjectRestoreGeneratedOutputInput = z.input<
+  typeof ProjectRestoreGeneratedOutputInputSchema
+>;
 export type ProjectListFilesInput = z.input<typeof ProjectListFilesInputSchema>;
 export type ProjectSearchFilesInput = z.input<typeof ProjectSearchFilesInputSchema>;
 export type ProjectDeleteFileInput = z.input<typeof ProjectDeleteFileInputSchema>;