@jpcasabiancai/cayenne 0.3.0 → 0.3.2

package/dist/cli.js

@@ -73,6 +73,38 @@ var init_constants = __esm({
   }
 });
 
+// ../../packages/shared/src/protocol/attachments.ts
+function sniffImage(bytes) {
+  if (startsWith(bytes, PNG)) return "image/png";
+  if (startsWith(bytes, JPEG)) return "image/jpeg";
+  if (startsWith(bytes, GIF87A) || startsWith(bytes, GIF89A)) return "image/gif";
+  if (startsWith(bytes, RIFF) && startsWith(bytes, WEBP, 8)) return "image/webp";
+  return null;
+}
+var ATTACHMENT_MAX_BYTES, ATTACHMENT_MAX_COUNT, ATTACHMENT_MEDIA_TYPES, ATTACHMENT_NAME, startsWith, ascii, PNG, JPEG, GIF87A, GIF89A, RIFF, WEBP;
+var init_attachments = __esm({
+  "../../packages/shared/src/protocol/attachments.ts"() {
+    "use strict";
+    ATTACHMENT_MAX_BYTES = 5 * 1024 * 1024;
+    ATTACHMENT_MAX_COUNT = 4;
+    ATTACHMENT_MEDIA_TYPES = {
+      "image/png": "png",
+      "image/jpeg": "jpg",
+      "image/webp": "webp",
+      "image/gif": "gif"
+    };
+    ATTACHMENT_NAME = /^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.(png|jpg|webp|gif)$/;
+    startsWith = (bytes, prefix, offset = 0) => bytes.length >= offset + prefix.length && prefix.every((b, i) => bytes[offset + i] === b);
+    ascii = (s) => Array.from(s, (c) => c.charCodeAt(0));
+    PNG = [137, 80, 78, 71, 13, 10, 26, 10];
+    JPEG = [255, 216, 255];
+    GIF87A = ascii("GIF87a");
+    GIF89A = ascii("GIF89a");
+    RIFF = ascii("RIFF");
+    WEBP = ascii("WEBP");
+  }
+});
+
 // ../../packages/shared/src/protocol/git.ts
 import { z } from "zod";
 var WORKTREE_NAME, GIT_REF, REF_FORBIDDEN, isGitRef, ABSOLUTE, escapes, NUL, AbsoluteDir, RepoRelativePath, GitRef, WorktreeName, GitPayloads, GitFileStatus, GitStatusFile, GitStatus, GitDiffFile, GitDiff, GitBranch, GitBranches, GitWorktreeCreated, GitWorktreeRemoved;
@@ -284,6 +316,7 @@ var PermissionMode, PermissionDecision, Provider, Effort, CommandPayloads, kinds
 var init_command = __esm({
   "../../packages/shared/src/protocol/command.ts"() {
     "use strict";
+    init_attachments();
     init_git();
     init_github();
     init_terminal();
@@ -324,13 +357,42 @@ var init_command = __esm({
         effort: Effort.optional(),
         model: z4.string().optional(),
         resumeProviderSessionId: z4.string().optional(),
+        // Duplicate a chat (D36): start from a fork of `resumeProviderSessionId` instead of appending
+        // to its transcript. Claude-only, no `worktree`. The runner additionally refuses a source that
+        // is not the caller's own Claude session on this runner, or a cwd other than the source's own directory.
+        forkSession: z4.boolean().optional(),
         initialPrompt: z4.string().optional(),
         title: z4.string().max(200).optional()
+      }).superRefine((p, ctx) => {
+        if (p.forkSession !== true) return;
+        if (p.resumeProviderSessionId === void 0) {
+          ctx.addIssue({
+            code: "custom",
+            message: "forkSession needs resumeProviderSessionId",
+            path: ["forkSession"]
+          });
+        }
+        if (p.worktree !== void 0) {
+          ctx.addIssue({
+            code: "custom",
+            message: "a forked session keeps its working directory",
+            path: ["worktree"]
+          });
+        }
+        if (p.provider === "codex") {
+          ctx.addIssue({
+            code: "custom",
+            message: "codex sessions cannot be forked",
+            path: ["provider"]
+          });
+        }
       }),
       "session.prompt": z4.object({
         text: z4.string().min(1).max(2e5),
         clientUuid: z4.uuid(),
-        attachments: z4.array(z4.object({ kind: z4.literal("image"), storagePath: z4.string() })).default([]),
+        // Images uploaded to the private `attachments` bucket (D37). No mediaType: the runner sniffs
+        // the bytes. The runner still checks each path against the session's own row (R31).
+        attachments: z4.array(z4.object({ kind: z4.literal("image"), storagePath: z4.string().regex(ATTACHMENT_NAME) })).max(ATTACHMENT_MAX_COUNT).default([]),
         memoryContext: z4.string().max(2e4).optional()
       }),
       "session.permission.respond": z4.object({
@@ -401,6 +463,7 @@ var ContentBlock, MessageRole, ChatMessageRow, PermissionRequestRow, CodexQuesti
 var init_content = __esm({
   "../../packages/shared/src/protocol/content.ts"() {
     "use strict";
+    init_attachments();
     ContentBlock = z5.discriminatedUnion("type", [
       z5.object({ type: z5.literal("text"), text: z5.string() }),
       z5.object({ type: z5.literal("thinking"), text: z5.string() }),
@@ -417,7 +480,14 @@ var init_content = __esm({
         isError: z5.boolean().default(false),
         structured: z5.unknown().optional()
       }),
-      z5.object({ type: z5.literal("image"), storagePath: z5.string(), mediaType: z5.string() }),
+      // The path is checked here, not only where it is used: the session owner may insert any
+      // `content` (0003 `messages_insert`), and a reader's browser signs whatever path a block names.
+      // A block that is not a canonical attachment name drops the row rather than steering that request.
+      z5.object({
+        type: z5.literal("image"),
+        storagePath: z5.string().regex(ATTACHMENT_NAME),
+        mediaType: z5.enum(Object.keys(ATTACHMENT_MEDIA_TYPES))
+      }),
       z5.object({
         type: z5.literal("result"),
         isError: z5.boolean(),
@@ -634,6 +704,18 @@ var init_runner = __esm({
        * cannot grant a terminal. Optional so an older row still parses.
        */
       memberTerminalIds: z8.array(z8.uuid()).max(64).optional(),
+      /**
+       * Whether this runner honours `session.start { forkSession: true }` (D36, protocol §9). An older
+       * runner strips the field and then refuses the resume under R30, so a client sends
+       * `forkSession` only when this is true. Absent reads as false; optional so an older row parses.
+       */
+      sessionFork: z8.boolean().optional(),
+      /**
+       * Whether this runner sends `session.prompt` attachments to the provider (D37, R31, protocol §9).
+       * An older runner parses `attachments` and ignores them, so a client offers images only when
+       * this is true. Absent reads as false; optional so an older row parses.
+       */
+      promptImages: z8.boolean().optional(),
       /**
        * The raw Ed25519 public key of the running process (32 bytes, unpadded base64url), which signs
        * the local server's `hello` (protocol §6.2). New on every start, republished by every capabilities refresh that changes the row;
@@ -650,6 +732,21 @@ var init_runner = __esm({
   }
 });
 
+// ../../packages/shared/src/protocol/session.ts
+import { z as z9 } from "zod";
+var SlashCommand, SessionCommandsListed;
+var init_session = __esm({
+  "../../packages/shared/src/protocol/session.ts"() {
+    "use strict";
+    SlashCommand = z9.object({
+      name: z9.string(),
+      description: z9.string(),
+      argumentHint: z9.string()
+    });
+    SessionCommandsListed = z9.object({ slashCommands: z9.array(SlashCommand) });
+  }
+});
+
 // ../../packages/shared/src/protocol/transport.ts
 var init_transport = __esm({
   "../../packages/shared/src/protocol/transport.ts"() {
@@ -661,6 +758,7 @@ var init_transport = __esm({
 var init_protocol = __esm({
   "../../packages/shared/src/protocol/index.ts"() {
     "use strict";
+    init_attachments();
     init_command();
     init_content();
     init_events();
@@ -668,6 +766,7 @@ var init_protocol = __esm({
     init_github();
     init_local();
     init_runner();
+    init_session();
     init_terminal();
     init_transport();
   }
@@ -817,7 +916,7 @@ import {
 } from "fs";
 import { homedir as homedir2 } from "os";
 import { dirname, isAbsolute as isAbsolute2, join as join3 } from "path";
-import { z as z9 } from "zod";
+import { z as z10 } from "zod";
 function setProfileOverride(name) {
   profileOverride = name;
 }
@@ -892,24 +991,24 @@ var init_config = __esm({
     init_cloud();
     init_profile();
     MEMBER_TERMINALS_ERROR = "allowMemberTerminals must be false or a list of user ids";
-    RunnerConfig = z9.object({
-      supabaseUrl: z9.url(),
-      supabaseAnonKey: z9.string().min(1),
-      workspaceId: z9.uuid().optional(),
-      runnerId: z9.uuid().optional(),
-      name: z9.string().optional(),
-      roots: z9.array(z9.string()).default([]),
-      port: z9.number().int().default(LOCAL_PORT),
+    RunnerConfig = z10.object({
+      supabaseUrl: z10.url(),
+      supabaseAnonKey: z10.string().min(1),
+      workspaceId: z10.uuid().optional(),
+      runnerId: z10.uuid().optional(),
+      name: z10.string().optional(),
+      roots: z10.array(z10.string()).default([]),
+      port: z10.number().int().default(LOCAL_PORT),
       /** Extra page origins the local server admits, beside the built-in list (`buildOrigins`). */
-      localOrigins: z9.array(z9.string()).default([]),
-      allowBypassPermissions: z9.boolean().default(false),
+      localOrigins: z10.array(z10.string()).default([]),
+      allowBypassPermissions: z10.boolean().default(false),
       /** Absolute path to the `codex` binary, when it is not on the daemon's PATH. */
-      codexPath: z9.string().optional(),
+      codexPath: z10.string().optional(),
       /**
        * The Claude Code config directory this profile's sessions run on (D33), handed to them as
        * `CLAUDE_CONFIG_DIR`. Unset means the CLI's own default, `~/.claude`.
        */
-      claudeConfigDir: z9.string().optional(),
+      claudeConfigDir: z10.string().optional(),
       /**
        * Who besides the runner owner may hold a terminal here (D34, plan ruling 14): `false`, or the
        * user ids this machine's owner names. Machine-local like `allowBypassPermissions`: a workspace
@@ -917,15 +1016,15 @@ var init_config = __esm({
        * `true` is refused — there is no "every member" switch. A listed member's shell runs as this
        * machine's OS user; the env allowlist is not a boundary.
        */
-      allowMemberTerminals: z9.union(
+      allowMemberTerminals: z10.union(
         [
-          z9.literal(false),
-          z9.array(z9.uuid({ error: MEMBER_TERMINALS_ERROR }), { error: MEMBER_TERMINALS_ERROR }).max(64, { error: MEMBER_TERMINALS_ERROR })
+          z10.literal(false),
+          z10.array(z10.uuid({ error: MEMBER_TERMINALS_ERROR }), { error: MEMBER_TERMINALS_ERROR }).max(64, { error: MEMBER_TERMINALS_ERROR })
         ],
         { error: MEMBER_TERMINALS_ERROR }
       ).default(false),
       /** Minutes a terminal nobody attends stays alive before the runner kills it (features §2). */
-      terminalIdleMinutes: z9.number().int().min(1).max(1440).default(10)
+      terminalIdleMinutes: z10.number().int().min(1).max(1440).default(10)
     });
     memberTerminalIdsOf = (cfg) => cfg.allowMemberTerminals === false ? [] : [...cfg.allowMemberTerminals];
     configPath = (dir) => join3(dir, "config.json");
@@ -1170,7 +1269,7 @@ import {
 } from "fs";
 import { uptime } from "os";
 import { join as join5 } from "path";
-import { z as z10 } from "zod";
+import { z as z11 } from "zod";
 function bootedAt(now = Date.now()) {
   return new Date(Math.round((now - uptime() * 1e3) / 1e3) * 1e3).toISOString();
 }
@@ -1313,13 +1412,13 @@ var LockRecord, BOOT_DRIFT_MS, ATTEMPTS, BACKOFF_MS, CLAIM_TTL_MS, errno, claimO
 var init_lock = __esm({
   "src/lock.ts"() {
     "use strict";
-    LockRecord = z10.object({
-      pid: z10.number().int().positive(),
-      profile: z10.string(),
-      startedAt: z10.string(),
+    LockRecord = z11.object({
+      pid: z11.number().int().positive(),
+      profile: z11.string(),
+      startedAt: z11.string(),
       /** `bootedAt()` when the lock was taken; a lock from another boot is stale whatever its pid. */
-      bootedAt: z10.string(),
-      version: z10.string()
+      bootedAt: z11.string(),
+      version: z11.string()
     });
     BOOT_DRIFT_MS = 1e4;
     ATTEMPTS = 8;
@@ -3062,7 +3161,7 @@ function createTokenVerifier({
     }
     return false;
   };
-  const refuse = (k) => {
+  const refuse2 = (k) => {
     cache.set(k, { userId: null, exp: 0, until: now() + negativeTtlMs });
     return { status: "refused" };
   };
@@ -3073,19 +3172,19 @@ function createTokenVerifier({
       const hit = cache.get(k);
       if (hit && hit.until > now()) {
         if (hit.userId === null) return { status: "refused" };
-        if (hit.exp * 1e3 <= now()) return refuse(k);
+        if (hit.exp * 1e3 <= now()) return refuse2(k);
         return { status: "valid", userId: hit.userId, exp: hit.exp };
       }
       cache.delete(k);
       const claims = claimsOf(token);
-      if (!claims || claims.exp * 1e3 <= now() || !admit(claims.sub)) return refuse(k);
+      if (!claims || claims.exp * 1e3 <= now() || !admit(claims.sub)) return refuse2(k);
       if (!budgeted()) return { status: "unavailable" };
       const user = await db.auth.getUser(token).then(
         (r) => r.error ? retryable(r.error) ? void 0 : null : r.data.user,
         () => void 0
       );
       if (user === void 0) return { status: "unavailable" };
-      if (!user || user.id !== claims.sub) return refuse(k);
+      if (!user || user.id !== claims.sub) return refuse2(k);
       cache.set(k, { userId: user.id, exp: claims.exp, until: now() + ttlMs });
       return { status: "valid", userId: user.id, exp: claims.exp };
     }
@@ -3451,7 +3550,7 @@ function createLocalServer({
   server.headersTimeout = LOCAL_HANDSHAKE_TIMEOUT_MS;
   server.requestTimeout = LOCAL_HANDSHAKE_TIMEOUT_MS;
   server.keepAliveTimeout = 1e3;
-  const refuse = (socket, status) => {
+  const refuse2 = (socket, status) => {
     const text = status === 403 ? "Forbidden" : "Service Unavailable";
     socket.write(`HTTP/1.1 ${status} ${text}\r
 Connection: close\r
@@ -3463,11 +3562,11 @@ Content-Length: 0\r
   server.on("upgrade", (req, socket, head) => {
     const origin = req.headers.origin ?? "";
     if (req.url !== LOCAL_WS_PATH || !hostAllowed(req.headers.host) || !originAllowed(origin, origins)) {
-      refuse(socket, 403);
+      refuse2(socket, 403);
       return;
     }
     if (pendingUpgrades >= LOCAL_MAX_PENDING_UPGRADES || conns.size >= maxSockets) {
-      refuse(socket, 503);
+      refuse2(socket, 503);
       return;
     }
     pendingUpgrades += 1;
@@ -3811,6 +3910,69 @@ var init_roster = __esm({
   }
 });
 
+// src/sessions/attachments.ts
+import { rmSync as rmSync5 } from "fs";
+import { join as join15 } from "path";
+async function loadAttachments(db, scope, attachments) {
+  const prefix = `${scope.workspaceId.toLowerCase()}/${scope.sessionId.toLowerCase()}/`;
+  const named = attachments.map(({ storagePath }, i) => {
+    const match = ATTACHMENT_NAME.exec(storagePath);
+    const declared = match?.[3] === void 0 ? void 0 : TYPE_OF_EXT.get(match[3]);
+    if (!match || !storagePath.startsWith(prefix) || !declared)
+      throw refuse(i + 1, "not in this chat");
+    return { storagePath, declared };
+  });
+  const loaded = [];
+  for (const [i, { storagePath, declared }] of named.entries()) {
+    const n = i + 1;
+    let blob;
+    try {
+      const { data: data2, error } = await db.storage.from(ATTACHMENTS_BUCKET).download(storagePath);
+      if (error || !data2) throw refuse(n, "could not be read");
+      blob = data2;
+    } catch {
+      throw refuse(n, "could not be read");
+    }
+    if (blob.size > ATTACHMENT_MAX_BYTES) throw refuse(n, "too large");
+    let data;
+    try {
+      data = Buffer.from(await blob.arrayBuffer());
+    } catch {
+      throw refuse(n, "could not be read");
+    }
+    if (data.byteLength > ATTACHMENT_MAX_BYTES) throw refuse(n, "too large");
+    const sniffed = sniffImage(data);
+    if (!sniffed) throw refuse(n, "not a supported image");
+    if (sniffed !== declared) throw refuse(n, "not the image type its name says");
+    loaded.push({ storagePath, mediaType: sniffed, data });
+  }
+  return loaded;
+}
+function attachmentsTempDir(home, runnerId, sessionId) {
+  return join15(home, "tmp", "attachments", runnerId, sessionId);
+}
+function assertStagingInsideHome(home, dir) {
+  return assertInsideRootsOrAncestor(dir, [home]);
+}
+function clearAttachmentsTemp(home, runnerId) {
+  const dir = join15(home, "tmp", "attachments", runnerId);
+  assertStagingInsideHome(home, dir);
+  rmSync5(dir, { recursive: true, force: true });
+}
+var ATTACHMENTS_BUCKET, TYPE_OF_EXT, refuse;
+var init_attachments2 = __esm({
+  "src/sessions/attachments.ts"() {
+    "use strict";
+    init_src();
+    init_paths();
+    ATTACHMENTS_BUCKET = "attachments";
+    TYPE_OF_EXT = new Map(
+      Object.entries(ATTACHMENT_MEDIA_TYPES).map(([type, ext]) => [ext, type])
+    );
+    refuse = (n, reason) => new Error(`VALIDATION: attachment ${n}: ${reason}`);
+  }
+});
+
 // src/github/gh.ts
 import { execFile as execFile4 } from "child_process";
 import { promisify as promisify3 } from "util";
@@ -3962,11 +4124,12 @@ var init_refusals = __esm({
 });
 
 // src/sessions/handlers.ts
+import { ZodError } from "zod";
 function parsePayload(row, kind) {
   try {
     return parseCommand(row, kind);
   } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
+    const message = err instanceof ZodError ? err.issues.map((i) => i.message).join("; ") : err instanceof Error ? err.message : String(err);
     throw new Error(message.startsWith("VALIDATION:") ? message : `VALIDATION: ${message}`);
   }
 }
@@ -4354,7 +4517,7 @@ import { randomUUID as randomUUID3 } from "crypto";
 import { EventEmitter } from "events";
 import { query as sdkQuery } from "@anthropic-ai/claude-agent-sdk";
 var ClaudeSession;
-var init_session = __esm({
+var init_session2 = __esm({
   "src/claude/session.ts"() {
     "use strict";
     init_src();
@@ -4364,7 +4527,7 @@ var init_session = __esm({
       constructor(opts) {
         super();
         this.opts = opts;
-        this.providerSessionId = opts.resume ?? null;
+        this.providerSessionId = opts.forkSession ? null : opts.resume ?? null;
       }
       opts;
       provider = "claude";
@@ -4397,6 +4560,7 @@ var init_session = __esm({
             // Present only when asked for, so the default call stays the CLI's own behaviour.
             ...this.opts.strictMcpConfig === void 0 ? {} : { strictMcpConfig: this.opts.strictMcpConfig },
             ...this.opts.mcpServers === void 0 ? {} : { mcpServers: this.opts.mcpServers },
+            ...this.opts.forkSession ? { forkSession: true } : {},
             canUseTool,
             abortController: this.abort,
             stderr: (line) => {
@@ -4408,10 +4572,21 @@ var init_session = __esm({
         });
         this.pumping = this.pump();
       }
-      prompt(text, uuid) {
+      prompt(text, uuid, { images }) {
+        const content = images.length ? [
+          ...images.map((image) => ({
+            type: "image",
+            source: {
+              type: "base64",
+              media_type: image.mediaType,
+              data: image.data.toString("base64")
+            }
+          })),
+          { type: "text", text }
+        ] : text;
         this.inbox.push({
           type: "user",
-          message: { role: "user", content: text },
+          message: { role: "user", content },
           parent_tool_use_id: null,
           uuid,
           session_id: this.providerSessionId ?? void 0
@@ -4640,15 +4815,22 @@ var init_policy = __esm({
 
 // src/codex/session.ts
 import { spawn as spawn2 } from "child_process";
+import { randomUUID as randomUUID4 } from "crypto";
 import { EventEmitter as EventEmitter2 } from "events";
+import { chmodSync as chmodSync4, lstatSync as lstatSync4, mkdirSync as mkdirSync6, rmdirSync, rmSync as rmSync6, writeFileSync as writeFileSync5 } from "fs";
+import { dirname as dirname7, join as join16 } from "path";
+function removeFiles(files) {
+  for (const file of files) rmSync6(file, { force: true });
+}
 function scrubSecrets(text) {
   return SECRET_PATTERNS.reduce((acc, [pattern, to]) => acc.replace(pattern, to), text);
 }
 var STDERR_TAIL_MAX, SIGKILL_AFTER_MS, SECRET_PATTERNS, APPROVAL_METHODS, CodexSession;
-var init_session2 = __esm({
+var init_session3 = __esm({
   "src/codex/session.ts"() {
     "use strict";
     init_src();
+    init_attachments2();
     init_normalize2();
     init_policy();
     init_rpc();
@@ -4692,6 +4874,8 @@ var init_session2 = __esm({
       turnId = null;
       running = false;
       queue = [];
+      /** The image files of the turn in flight, removed when it ends. */
+      turnFiles = [];
       approvals = /* @__PURE__ */ new Map();
       streaming = /* @__PURE__ */ new Set();
       stderrTail = [];
@@ -4715,6 +4899,7 @@ var init_session2 = __esm({
           const tail = this.stderrTail.length ? `
 ${scrubSecrets(this.stderrTail.join("")).slice(-STDERR_TAIL_MAX)}` : "";
           const error = this.stopping || code === 0 ? null : `PROVIDER_ERROR: codex exited with ${code}${tail}`;
+          this.removeAllFiles();
           this.emit("exit", { error });
         });
         const rpc = new JsonRpc(child.stdin, child.stdout);
@@ -4754,19 +4939,88 @@ ${scrubSecrets(this.stderrTail.join("")).slice(-STDERR_TAIL_MAX)}` : "";
         });
         this.flush();
       }
-      prompt(text, _uuid) {
-        this.queue.push(text);
+      /**
+       * Queue one turn with images `stageImages` already wrote. From here the session owns the files
+       * and removes them when the turn ends, fails, or the session stops.
+       */
+      prompt(text, _uuid, staged) {
+        if (staged.files.length !== staged.images.length) {
+          throw new Error("PROVIDER_ERROR: codex images must be staged before the prompt");
+        }
+        this.queue.push({ text, files: [...staged.files] });
         this.flush();
       }
+      /**
+       * Write the images Codex will read, synchronously, before the manager persists anything. A
+       * failure removes whatever was written and throws, so a refused prompt leaves no file behind.
+       */
+      stageImages(images) {
+        const files = this.writeImages(images);
+        return { images, files, discard: () => removeFiles(files) };
+      }
+      writeImages(images) {
+        if (images.length === 0) return [];
+        const dir = this.opts.attachmentsDir;
+        const home = this.opts.attachmentsHome;
+        if (!dir || !home) {
+          throw new Error("PROVIDER_ERROR: this codex session has no attachments directory");
+        }
+        const written = [];
+        try {
+          assertStagingInsideHome(home, dir);
+          mkdirSync6(dir, { recursive: true, mode: 448 });
+          assertStagingInsideHome(home, dir);
+          for (const path of [dirname7(dir), dir]) {
+            const st = lstatSync4(path);
+            if (st.isSymbolicLink() || !st.isDirectory()) {
+              throw new Error(`${path} is not a plain directory`);
+            }
+          }
+          chmodSync4(dir, 448);
+          for (const image of images) {
+            const path = join16(dir, `${randomUUID4()}.${ATTACHMENT_MEDIA_TYPES[image.mediaType]}`);
+            writeFileSync5(path, image.data, { mode: 384, flag: "wx" });
+            written.push(path);
+          }
+        } catch (err) {
+          removeFiles(written);
+          const detail = err instanceof Error ? err.message : String(err);
+          throw new Error(`PROVIDER_ERROR: could not write an image for codex: ${detail}`);
+        }
+        return written;
+      }
+      /** The turn in flight is over: its images have been read, or never will be. */
+      endTurnFiles() {
+        removeFiles(this.turnFiles);
+        this.turnFiles = [];
+      }
+      removeAllFiles() {
+        this.endTurnFiles();
+        for (const turn of this.queue) {
+          removeFiles(turn.files);
+          turn.files = [];
+        }
+        if (this.opts.attachmentsDir) {
+          try {
+            rmdirSync(this.opts.attachmentsDir);
+          } catch {
+          }
+        }
+      }
       /** One turn at a time: Codex has no notion of a second concurrent turn on a thread. */
       flush() {
         if (this.running || !this.rpc || !this.providerSessionId) return;
         const next = this.queue.shift();
         if (next === void 0) return;
         this.running = true;
+        this.turnFiles = next.files;
         void this.rpc.request("turn/start", {
           threadId: this.providerSessionId,
-          input: [{ type: "text", text: next }],
+          // app-server v2 `UserInput`: images as `localImage` paths, then the text.
+          input: [
+            ...next.files.map((path) => ({ type: "localImage", path })),
+            { type: "text", text: next.text }
+          ],
           sandboxPolicy: this.sandbox,
           ...this.pendingModel ? { model: this.pendingModel } : {},
           ...this.pendingEffort ? { effort: this.pendingEffort } : {}
@@ -4774,6 +5028,7 @@ ${scrubSecrets(this.stderrTail.join("")).slice(-STDERR_TAIL_MAX)}` : "";
           this.turnId = res.turnId ?? null;
         }).catch((err) => {
           this.running = false;
+          this.endTurnFiles();
           this.emit("result", {
             isError: true,
             durationMs: 0,
@@ -4810,6 +5065,7 @@ ${scrubSecrets(this.stderrTail.join("")).slice(-STDERR_TAIL_MAX)}` : "";
           case "turn/failed": {
             this.running = false;
             this.turnId = null;
+            this.endTurnFiles();
             const status = params.status ?? (method === "turn/failed" ? "failed" : "completed");
             this.emit("result", {
               isError: status === "failed",
@@ -4964,6 +5220,7 @@ ${scrubSecrets(this.stderrTail.join("")).slice(-STDERR_TAIL_MAX)}` : "";
           this.emit("permissionTimeout", { id });
         }
         await this.interrupt();
+        this.removeAllFiles();
         this.rpc?.close();
         this.child?.stdin?.end();
         const child = this.child;
@@ -4991,13 +5248,27 @@ function createProviderSession(provider, opts) {
 var init_create = __esm({
   "src/providers/create.ts"() {
     "use strict";
-    init_session();
     init_session2();
+    init_session3();
+  }
+});
+
+// src/providers/types.ts
+var inMemoryImages;
+var init_types = __esm({
+  "src/providers/types.ts"() {
+    "use strict";
+    inMemoryImages = (images) => ({
+      images,
+      files: [],
+      discard: () => {
+      }
+    });
   }
 });
 
 // src/sessions/manager.ts
-import { randomUUID as randomUUID4 } from "crypto";
+import { randomUUID as randomUUID5 } from "crypto";
 import { realpathSync as realpathSync7 } from "fs";
 import { isAbsolute as isAbsolute10, sep as sep5 } from "path";
 import { isDeepStrictEqual } from "util";
@@ -5026,12 +5297,15 @@ var init_manager = __esm({
   "src/sessions/manager.ts"() {
     "use strict";
     init_src();
+    init_config();
     init_introspect();
     init_watch();
     init_worktree();
     init_worktree_owners();
     init_paths();
     init_create();
+    init_types();
+    init_attachments2();
     isAtOrBelow = (p, dir) => p === dir || p.startsWith(dir.endsWith(sep5) ? dir : `${dir}${sep5}`);
     DENY_MESSAGE_MAX = 2e3;
     EXIT_ERROR_MAX = 8 * 1024;
@@ -5095,10 +5369,16 @@ var init_manager = __esm({
         }
         this.assertModeAllowed(p.permissionMode);
         const provider = p.provider ?? "claude";
+        if (p.forkSession && provider !== "claude") {
+          throw new Error("VALIDATION: codex sessions cannot be forked");
+        }
         this.assertProviderAllowed(provider, createdBy);
         const typed = resolveInsideRoots(p.cwd, this.deps.roots);
         this.assertNotRemoving(typed.real);
-        if (p.resumeProviderSessionId !== void 0) {
+        const forking = p.forkSession === true && p.resumeProviderSessionId !== void 0;
+        if (forking) {
+          await this.assertForkable(p.resumeProviderSessionId, createdBy, typed.real);
+        } else if (p.resumeProviderSessionId !== void 0) {
           await this.assertResumable(sessionId, p.resumeProviderSessionId);
         }
         let { real: cwd, root } = typed;
@@ -5106,7 +5386,7 @@ var init_manager = __esm({
         if (p.worktree) {
           cwd = await this.startWorktree(typed.real, typed.root, p.worktree, createdBy);
           inWorktree = true;
-        } else if (p.resumeProviderSessionId !== void 0) {
+        } else if (p.resumeProviderSessionId !== void 0 && !forking) {
           const recorded = await this.recordedWorktree(sessionId);
           if (recorded) ({ real: cwd, root } = recorded);
         }
@@ -5127,9 +5407,16 @@ var init_manager = __esm({
             permissionMode: p.permissionMode,
             model: p.model,
             resume: p.resumeProviderSessionId,
+            ...forking ? { forkSession: true } : {},
             ...provider === "codex" ? {
               codexPath: this.deps.codexPath,
               checkInput: this.codexGate(sessionId, cwd),
+              attachmentsHome: this.deps.cayenneHome ?? cayenneHome(),
+              attachmentsDir: attachmentsTempDir(
+                this.deps.cayenneHome ?? cayenneHome(),
+                this.deps.runnerId,
+                sessionId
+              ),
               ...p.effort ? { effort: p.effort } : {}
             } : this.isolation(createdBy)
           });
@@ -5137,7 +5424,9 @@ var init_manager = __esm({
           started();
         }
         if (inWorktree) await this.recordSessionWorktree(sessionId, cwd, root);
-        else if (p.resumeProviderSessionId === void 0) this.forgetSessionWorktree(sessionId);
+        else if (p.resumeProviderSessionId === void 0 || forking) {
+          this.forgetSessionWorktree(sessionId);
+        }
         live.status = "idle";
         await this.updateSession(sessionId, { status: "idle", model: p.model ?? null });
         await this.broadcast(sessionId, {
@@ -5157,30 +5446,61 @@ var init_manager = __esm({
         if (p.initialPrompt) {
           await this.prompt(
             sessionId,
-            { text: p.initialPrompt, clientUuid: randomUUID4(), attachments: [] },
+            { text: p.initialPrompt, clientUuid: randomUUID5(), attachments: [] },
             createdBy
           );
         }
         return { providerSessionId: live.session.providerSessionId };
       }
       async prompt(sessionId, p, createdBy) {
+        this.assertCodexOwner(sessionId, createdBy);
+        const images = p.attachments.length ? await loadAttachments(
+          this.deps.db,
+          { workspaceId: await this.sessionWorkspace(sessionId), sessionId },
+          p.attachments
+        ) : [];
         const live = await this.ensureLive(sessionId, createdBy);
         this.assertCodexOwner(sessionId, createdBy);
         const text = p.memoryContext ? wrapMemory(p.memoryContext, p.text) : p.text;
-        live.echoed.add(p.clientUuid);
-        await this.persist(
-          sessionId,
-          live,
-          "user",
-          [{ type: "text", text: p.text }],
-          p.clientUuid,
-          null,
-          null
-        );
-        await this.setStatus(sessionId, "running");
-        live.session.prompt(text, p.clientUuid);
+        const staged = images.length ? live.session.stageImages?.(images) ?? inMemoryImages(images) : inMemoryImages([]);
+        try {
+          live.echoed.add(p.clientUuid);
+          await this.persist(
+            sessionId,
+            live,
+            "user",
+            [
+              { type: "text", text: p.text },
+              ...images.map(
+                (image) => ({
+                  type: "image",
+                  storagePath: image.storagePath,
+                  mediaType: image.mediaType
+                })
+              )
+            ],
+            p.clientUuid,
+            null,
+            null
+          );
+          await this.setStatus(sessionId, "running");
+          live.session.prompt(text, p.clientUuid, staged);
+        } catch (err) {
+          staged.discard();
+          throw err;
+        }
         return { accepted: true };
       }
+      /**
+       * The session row's own workspace, which R31 checks attachment paths against. Read, never taken
+       * from the payload or assumed to be the runner's: the path prefix is the whole of the check.
+       */
+      async sessionWorkspace(sessionId) {
+        const { data, error } = await this.deps.db.from("chat_sessions").select("workspace_id").eq("id", sessionId).eq("runner_id", this.deps.runnerId).maybeSingle();
+        if (error) this.deps.log.warn({ err: error.message, sessionId }, "session read failed");
+        if (!data?.workspace_id) throw new Error("SESSION_NOT_FOUND");
+        return data.workspace_id;
+      }
       /**
        * Refuse unless `requestId` is a request this session is still holding.
        *
@@ -5584,6 +5904,37 @@ var init_manager = __esm({
           throw new Error("VALIDATION: resumeProviderSessionId does not belong to this session");
         }
       }
+      /**
+       * D36, amending R30 for `forkSession: true`: the resume id may be held by another session, but
+       * only one on this runner that `createdBy` owns — a member must not fork the runner owner's
+       * conversation, or anyone else's. A command with no creator owns nothing. Only a Claude row with
+       * a non-empty id can be a source. The new session must run where the source did, decided the way
+       * a resume of the source would be: the worktree this runner recorded for it, else its canonical
+       * `cwd`. Never `worktree_path`: the runner owner can rewrite that column on a member's chat, and
+       * it must not steer where the member's fork runs. A source path that no longer resolves inside
+       * the roots cannot be proved equal, so it is refused, not thrown through.
+       */
+      async assertForkable(providerSessionId, createdBy, cwd) {
+        if (providerSessionId === "") {
+          throw new Error("VALIDATION: forkSession source is not a session you own on this runner");
+        }
+        const { data, error } = await this.deps.db.from("chat_sessions").select("id, owner_id, cwd").eq("provider_session_id", providerSessionId).eq("runner_id", this.deps.runnerId).eq("provider", "claude").maybeSingle();
+        if (error) throw new Error(`PROVIDER_ERROR: could not read the session: ${error.message}`);
+        if (!data || createdBy === null || data.owner_id !== createdBy) {
+          throw new Error("VALIDATION: forkSession source is not a session you own on this runner");
+        }
+        let sourceCwd = (await this.recordedWorktree(data.id))?.real ?? null;
+        if (sourceCwd === null) {
+          try {
+            sourceCwd = resolveInsideRoots(data.cwd, this.deps.roots).real;
+          } catch {
+            sourceCwd = null;
+          }
+        }
+        if (sourceCwd !== cwd) {
+          throw new Error("VALIDATION: a forked session keeps its working directory");
+        }
+      }
       /**
        * Whether this runner may open a session on `provider` for `createdBy`.
        *
@@ -6259,9 +6610,9 @@ function createTerminalChannels({
       const inflight = joining.get(terminalId);
       if (inflight) return inflight;
       if (joined.has(terminalId)) return;
-      const join17 = attachOne(terminalId).finally(() => joining.delete(terminalId));
-      joining.set(terminalId, join17);
-      return join17;
+      const join19 = attachOne(terminalId).finally(() => joining.delete(terminalId));
+      joining.set(terminalId, join19);
+      return join19;
     },
     flush,
     detach,
@@ -6318,7 +6669,7 @@ var init_channels = __esm({
 // src/terminal/env.ts
 import { readFileSync as readFileSync7, realpathSync as realpathSync8 } from "fs";
 import { lstat } from "fs/promises";
-import { dirname as dirname7, isAbsolute as isAbsolute11, relative as relative4 } from "path";
+import { dirname as dirname8, isAbsolute as isAbsolute11, relative as relative4 } from "path";
 function terminalEnv(base, { runnerOwner, claudeConfigDir }) {
   const env = {};
   for (const [key, value] of Object.entries(base)) {
@@ -6374,7 +6725,7 @@ async function rootOwnedPath(fs, real) {
       return false;
     }
     if (st.isSymbolicLink() || st.uid !== 0 || (st.mode & 18) !== 0) return false;
-    const parent = dirname7(path);
+    const parent = dirname8(path);
     if (parent === path) return true;
     path = parent;
   }
@@ -7358,7 +7709,7 @@ __export(start_exports, {
   start: () => start
 });
 import { homedir as homedir3, hostname } from "os";
-import { join as join15 } from "path";
+import { join as join17 } from "path";
 function protectedPaths(claudeConfigDir, home = homedir3()) {
   const inHome = [
     ".claude",
@@ -7366,12 +7717,12 @@ function protectedPaths(claudeConfigDir, home = homedir3()) {
     ".codex",
     ".ssh",
     ".aws",
-    join15(".config", "gh"),
+    join17(".config", "gh"),
     ".gnupg",
     ".git-credentials",
     ".npmrc",
     ".netrc"
-  ].map((p) => join15(home, p));
+  ].map((p) => join17(home, p));
   return [cayenneHome(), ...claudeConfigDir ? [claudeConfigDir] : [], ...inHome];
 }
 function logCodex(codex) {
@@ -7517,7 +7868,11 @@ async function compose(cfg, lock, host, preflight) {
     claude: true,
     providers,
     // Who the runner's own config names (D34); every heartbeat refresh republishes it.
-    memberTerminalIds: [...memberTerminalIds]
+    memberTerminalIds: [...memberTerminalIds],
+    // D36: this build forks a Claude session on `session.start { forkSession: true }`.
+    sessionFork: true,
+    // D37: this build loads image attachments on `session.prompt` under R31.
+    promptImages: true
   });
   const registered = capabilities();
   let loggedCodex = null;
@@ -7551,6 +7906,14 @@ async function compose(cfg, lock, host, preflight) {
     await local.close();
     throw err;
   }
+  try {
+    clearAttachmentsTemp(cayenneHome(), identity.runnerId);
+  } catch (err) {
+    logger.warn(
+      { err: err instanceof Error ? err.message : String(err) },
+      "could not clear staged attachment images"
+    );
+  }
   let stopHeartbeat = null;
   let roster = null;
   try {
@@ -7576,9 +7939,9 @@ async function compose(cfg, lock, host, preflight) {
       // The roster's own array, mutated in place: `serves` reads the live list with no restart.
       allowedMemberIds: liveRoster.allowedMemberIds,
       // Outside every profile and repository: the creator of a worktree is the machine's record.
-      worktreeOwners: createWorktreeOwners(join15(cayenneHome(), "worktrees")),
+      worktreeOwners: createWorktreeOwners(join17(cayenneHome(), "worktrees")),
       // Beside it: where each session was spawned, the only source of a resumed directory.
-      sessionWorktrees: createSessionWorktrees(join15(cayenneHome(), "session-worktrees")),
+      sessionWorktrees: createSessionWorktrees(join17(cayenneHome(), "session-worktrees")),
       roots,
       allowBypass: cfg.allowBypassPermissions,
       codexPath,
@@ -7838,6 +8201,7 @@ var init_start = __esm({
     init_profile();
     init_registry();
     init_roster();
+    init_attachments2();
     init_handlers();
     init_manager();
     init_supabase();
@@ -7851,9 +8215,9 @@ var init_start = __esm({
 });
 
 // src/cli.ts
-import { existsSync as existsSync5, mkdirSync as mkdirSync6, readFileSync as readFileSync8, realpathSync as realpathSync9, rmSync as rmSync5, writeFileSync as writeFileSync5 } from "fs";
+import { existsSync as existsSync5, mkdirSync as mkdirSync7, readFileSync as readFileSync8, realpathSync as realpathSync9, rmSync as rmSync7, writeFileSync as writeFileSync6 } from "fs";
 import { homedir as homedir4, hostname as hostname2, userInfo } from "os";
-import { dirname as dirname8, join as join16 } from "path";
+import { dirname as dirname9, join as join18 } from "path";
 import { Command } from "commander";
 import prompts from "prompts";
 
@@ -8308,8 +8672,8 @@ var service = () => {
   return { exec: exec4, launchd: makeLaunchd(exec4, userInfo().uid), label: plistLabel(currentProfile()) };
 };
 var writePlistFile = (path, xml2) => {
-  mkdirSync6(dirname8(path), { recursive: true });
-  writeFileSync5(path, xml2, { mode: 420 });
+  mkdirSync7(dirname9(path), { recursive: true });
+  writeFileSync6(path, xml2, { mode: 420 });
 };
 var requireMac = () => {
   if (process.platform !== "darwin") {
@@ -8455,7 +8819,7 @@ program.command("doctor").description("Check the install and say how to fix what
   if (checks.some((c) => !c.ok)) process.exitCode = 1;
 });
 program.command("logs").description("Show the service log").option("-f, --follow", "keep streaming").action(async (opts) => {
-  const file = join16(cayenneDir(), "logs", "runner.log");
+  const file = join18(cayenneDir(), "logs", "runner.log");
   if (!existsSync5(file)) throw new Error(`no log yet at ${file}. Run \`cayenne up\` first.`);
   const print = (chunk) => {
     for (const line of chunk.split("\n")) {
@@ -8501,7 +8865,7 @@ program.command("update").description("Re-pin the installed app and restart the
       cliPath: record.cliPath,
       profile: currentProfile(),
       pathEnv: record.pathEnv,
-      logDir: join16(dir, "logs")
+      logDir: join18(dir, "logs")
     })
   );
   await launchd.bootout(label);
@@ -8512,7 +8876,7 @@ program.command("uninstall").description("Stop the service and remove the launch
   requireMac();
   const { launchd, label } = service();
   await launchd.bootout(label);
-  rmSync5(plistPath(label, homedir4()), { force: true });
+  rmSync7(plistPath(label, homedir4()), { force: true });
   if (!opts.purge) {
     console.log(`removed ${label}`);
     return;
@@ -8522,7 +8886,7 @@ program.command("uninstall").description("Stop the service and remove the launch
   if (dir === "/" || dir === home || home.startsWith(`${dir}/`)) {
     throw new Error(`refusing to purge ${dir}: it is the home directory or an ancestor of it`);
   }
-  if (!existsSync5(join16(dir, "config.json")) && !existsSync5(join16(dir, "app", "install.json"))) {
+  if (!existsSync5(join18(dir, "config.json")) && !existsSync5(join18(dir, "app", "install.json"))) {
     throw new Error(`refusing to purge ${dir}: it does not look like a Cayenne profile`);
   }
   if (!opts.yes) {
@@ -8536,7 +8900,7 @@ program.command("uninstall").description("Stop the service and remove the launch
       "could not revoke the stored session (offline?) \u2014 sign out from the web app to be sure"
     );
   }
-  rmSync5(dir, { recursive: true, force: true });
+  rmSync7(dir, { recursive: true, force: true });
   console.log(`removed ${label} and ${dir}`);
 });
 program.parseAsync(process.argv).catch((err) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jpcasabiancai/cayenne",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "files": [
     "dist/cli.js"
   ],
@@ -42,8 +42,8 @@
     "tsx": "4.23.13",
     "typescript": "~5.9.3",
     "vitest": "5.0.0",
-    "@cayenne/shared": "0.0.1",
-    "@cayenne/db": "0.0.1"
+    "@cayenne/db": "0.0.1",
+    "@cayenne/shared": "0.0.1"
   },
   "scripts": {
     "cli": "tsx src/cli.ts",