feat(protocol+sdk+server): attachments — workdir uploads at session create

Lets clients ship per-request files into the agent's workdir before the
engine starts. Files overlay on top of the loader-materialized GAP repo
(caller wins on path collisions). Path-jailed by the existing harness
fs helpers — '..', absolute paths, and symlink-outs return 400.

Wire shape (CreateSessionBody.attachments + RunBody.attachments):

  attachments: [
    { path: "data.csv",   content: "name,age\nA,30\n" },
    { path: "report.pdf", content: "JVBERi0...",  encoding: "base64" }
  ]

Architecture: zero changes at the engine or substrate layer. The workdir
is the universal interface — every engine (claude-agent-sdk, gitagent,
deepagents) already operates on cwd via its native tools, and every
substrate (local, bwrap, e2b, vzvm) already exposes the workdir to its
harness child. We just write the files once at session-create time,
inside the harness-server's createSession service, between
loader.load() and engine startup.

Files touched:
- packages/protocol/src/harness-rest.ts: new Attachment zod schema +
  CreateSessionBody.attachments field
- packages/harness-server/src/services/create-session.ts:
  materializeAttachments helper after loader.load; PATH_ESCAPE maps to
  400 with the attempted path; one info log per attachment
- packages/sdk/src/types.ts: ComputerAgentOptions.attachments
- packages/sdk/src/computer-agent.ts: forwards attachments into the
  session create body
- examples/computeragent-server.ts: RunBody.attachments → passed to
  ComputerAgent constructor

Verified locally end-to-end on LocalSubstrate:
  - POST /run with attachments [secret.txt utf8, binary.bin base64]
  - Both written to workdir (harness logs: session.attachment.written)
  - Agent read secret.txt back via Bash, replied with exact content

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: kapaleshreyas

examples/computeragent-server.ts

@@ -115,6 +115,21 @@ interface RunBody {
    * Pair with `sessionId` to resume an existing conversation across processes.
    */
   sessionStore?: { kind: string; options?: unknown };
+  /**
+   * Files to land in the agent's workdir BEFORE the engine starts. Written
+   * AFTER the GAP repo is materialized, so attachments overlay on top
+   * (caller wins on path collisions). Path-jailed by the harness server.
+   *
+   *   attachments: [
+   *     { path: "input.csv",  content: "name,age\nA,30\n" },
+   *     { path: "report.pdf", content: "JVBERi0...", encoding: "base64" }
+   *   ]
+   *
+   * The agent's tools (Read, Bash, etc.) see them as regular files in cwd.
+   * Works with any substrate (local/bwrap/e2b) and any harness — files
+   * are written once into the workdir, every engine sees them natively.
+   */
+  attachments?: Array<{ path: string; content: string; encoding?: "utf8" | "base64" }>;
 }
 
 interface ActiveRun {
@@ -213,6 +228,9 @@ export class ComputerAgentServer {
         ...(body.sessionId ? { sessionId: body.sessionId } : {}),
         ...(body.debug ? { debug: true } : {}),
         ...(body.sessionStore ? { sessionStore: body.sessionStore as never } : {}),
+        ...(body.attachments && body.attachments.length > 0
+          ? { attachments: body.attachments }
+          : {}),
       });
 
       // Track the agent so /artifact can find it by sessionId while the run is live.
@@ -451,7 +469,7 @@ if (import.meta.url === `file://${process.argv[1]}`) {
   console.log("");
   console.log("Endpoints:");
   console.log("  GET  /health                    runtimes + default + active count");
-  console.log("  POST /run                       body: {source, harness, runtime?, message, envs?, options?, gitToken?, model?, sessionStore?, sessionId?, debug?}");
+  console.log("  POST /run                       body: {source, harness, runtime?, message, envs?, options?, gitToken?, model?, sessionStore?, sessionId?, debug?, attachments?}");
   console.log("  GET  /workdir?sessionId=<id>");
   console.log("  GET  /artifact?sessionId=<id>&path=<path>");
   console.log("");

packages/harness-server/src/services/create-session.ts

@@ -2,10 +2,12 @@ import { mkdtemp, mkdir } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { randomUUID } from "node:crypto";
-import type { CreateSessionBody } from "@computeragent/protocol";
+import type { Attachment, CreateSessionBody } from "@computeragent/protocol";
 import { Session } from "../session.js";
 import { SessionRegistry } from "../registry.js";
 import { BadRequest } from "../error-mapper.js";
+import { PathEscapeError } from "../path-jail.js";
+import { writeBytes } from "./workspace-fs.js";
 import type { ServerDeps } from "../app.js";
 import { resolveStore } from "../stores/registry.js";
 import { wrapValidatingStore } from "../stores/validating-store.js";
@@ -43,6 +45,14 @@ export async function createSession(
     workdir,
   });
 
+  // Materialize caller-supplied attachments on top of the loader's output.
+  // Order matters: loader runs first (GAP repo files), then attachments
+  // overlay — so a per-request file overrides a repo file with the same
+  // name. Path-jailed by writeBytes; out-of-workdir paths → 400.
+  if (body.attachments && body.attachments.length > 0) {
+    await materializeAttachments(workdir, body.attachments, deps.logger);
+  }
+
   const merged = mergeEngineOptions(result.options, body.options);
   const final = result.harden ? result.harden(merged) : merged;
 
@@ -122,3 +132,37 @@ function mergeEngineOptions(loaderOpts: unknown, bodyOpts: Record<string, unknow
   if (!loaderOpts || typeof loaderOpts !== "object" || Array.isArray(loaderOpts)) return bodyOpts;
   return { ...(loaderOpts as Record<string, unknown>), ...bodyOpts };
 }
+
+/**
+ * Write each attachment into the workdir before the engine starts.
+ *
+ * Path-jailed via `writeBytes` — relative paths that resolve outside the
+ * workdir are rejected with 400 PATH_ESCAPE. Binary uploads use
+ * `encoding: "base64"`; text uses `encoding: "utf8"` (default).
+ *
+ * One log line per attachment so the deployment is auditable.
+ */
+async function materializeAttachments(
+  workdir: string,
+  attachments: readonly Attachment[],
+  logger: ServerDeps["logger"],
+): Promise<void> {
+  for (const att of attachments) {
+    const encoding = att.encoding ?? "utf8";
+    const bytes =
+      encoding === "base64" ? Buffer.from(att.content, "base64") : Buffer.from(att.content, "utf8");
+    try {
+      const { size } = await writeBytes(workdir, att.path, bytes);
+      logger.info("session.attachment.written", { path: att.path, bytes: size, encoding });
+    } catch (err) {
+      if (err instanceof PathEscapeError) {
+        throw BadRequest(
+          "PATH_ESCAPE",
+          `attachment path '${err.attempted}' resolves outside the session workdir`,
+          { attempted: err.attempted },
+        );
+      }
+      throw err;
+    }
+  }
+}

packages/protocol/src/harness-rest.ts

@@ -22,6 +22,22 @@ export const UserMessage = z.object({
 });
 export type UserMessage = z.infer<typeof UserMessage>;
 
+/**
+ * File the caller wants to land in the session workdir before the engine starts.
+ *
+ * - `path` is relative to the workdir. Path-jailed: `..`, absolute paths, and
+ *   symlink-outs are rejected with 400 PATH_ESCAPE.
+ * - `content` is the file body. UTF-8 strings (default) or base64 for binary.
+ * - Written AFTER the identity loader materializes the GAP repo, so attachments
+ *   overlay on top of repo files (caller wins on collisions).
+ */
+export const Attachment = z.object({
+  path: z.string().min(1),
+  content: z.string(),
+  encoding: z.enum(["utf8", "base64"]).optional(),
+});
+export type Attachment = z.infer<typeof Attachment>;
+
 /** Identity reference: which loader, with which source. */
 export const IdentityRef = z.object({
   loader: z.string().min(1),
@@ -51,6 +67,14 @@ export const CreateSessionBody = z.object({
    * `sessionId` IS the resume signal — no separate flag.
    */
   sessionStore: SessionStoreConfig.optional(),
+  /**
+   * Files to materialize into the session workdir before the engine starts.
+   * Written AFTER the identity loader populates the workdir, so an
+   * attachment with the same name as a repo file overwrites it (caller
+   * wins). Common uses: passing PDFs for analysis, CSVs for processing,
+   * config overlays per request.
+   */
+  attachments: z.array(Attachment).optional(),
 });
 export type CreateSessionBody = z.infer<typeof CreateSessionBody>;