feat(native-chat): attach files to a structured chat on a paired server

config/scripts/vitest-sqlite-runtime-files.mjs

@@ -35,6 +35,8 @@ export const SQLITE_RUNTIME_INCLUDE = [
   'src/main/ipc/ssh-host-partition-session-export.test.ts',
   'src/main/ipc/ssh-host-server-on-connect-wiring.test.ts',
   'src/main/ipc/ssh-managed-server-move-conversion.test.ts',
+  'src/main/native-chat/agent-session-attachments/agent-session-attachment-claims.test.ts',
+  'src/main/native-chat/agent-session-attachments/agent-session-attachment-sweep.test.ts',
   'src/main/native-chat/agent-session-wire/agent-session-history-byte-accounting.test.ts',
   'src/main/native-chat/agent-session-wire/agent-session-history-conversation-window.test.ts',
   'src/main/native-chat/agent-session-wire/agent-session-history-forward-read-budget.test.ts',
@@ -46,6 +48,7 @@ export const SQLITE_RUNTIME_INCLUDE = [
   'src/main/native-chat/agent-session-wire/structured-agent-session-append-delivery.test.ts',
   'src/main/native-chat/agent-session-wire/structured-agent-session-at-rest-commands.test.ts',
   'src/main/native-chat/agent-session-wire/structured-agent-session-attach-reconciliation.test.ts',
+  'src/main/native-chat/agent-session-wire/structured-agent-session-attachment-admission.test.ts',
   'src/main/native-chat/agent-session-wire/structured-agent-session-claude-compact-stop.test.ts',
   'src/main/native-chat/agent-session-wire/structured-agent-session-claude-echo-working.test.ts',
   'src/main/native-chat/agent-session-wire/structured-agent-session-claude-hung-start-stop.test.ts',
@@ -187,6 +190,7 @@ export const SQLITE_RUNTIME_INCLUDE = [
   'src/main/runtime/structured-agent-session-rollback-compatibility.test.ts',
   'src/main/runtime/structured-agent-session-spawn-token-descendants.test.ts',
   'src/main/runtime/structured-agent-session-startup-reconcile.test.ts',
+  'src/main/runtime/structured-claude-attachment-grant.test.ts',
   'src/main/runtime/structured-claude-pending-rewind.test.ts',
   'src/main/ssh-expired-lease-pane-readoption.test.ts',
   'src/main/ssh-reattach-pane-cardinality.test.ts',

src/main/claude/claude-structured-launch-resolution.test.ts

@@ -63,7 +63,8 @@ function resolverFor(
   // Manual by default so a test that is not about permissions is not silently about them.
   agentDefaultArgs: Record<string, string> = { claude: '' },
   hasTranscript: () => Promise<boolean> = async () => true,
-  resolveLaunchArgs?: () => string[]
+  resolveLaunchArgs?: () => string[],
+  attachmentDirectory?: string
 ) {
   return createClaudeStructuredLaunchResolver({
     store: { getRecord: () => value, pinLaunchDirectory: vi.fn() },
@@ -73,7 +74,8 @@ function resolverFor(
     resolvePermissionMode: () => claudeStructuredPermissionModeForSettings({ agentDefaultArgs }),
     hasTranscript,
     resolveLaunchArgs: resolveLaunchArgs ?? (() => value?.launchArgs ?? []),
-    ...(resolveEnv ? { resolveEnv } : {})
+    ...(resolveEnv ? { resolveEnv } : {}),
+    ...(attachmentDirectory ? { attachmentDirectory } : {})
   })
 }
 
@@ -424,6 +426,38 @@ describe('claude structured launch resolution', () => {
     }
   })
 
+  it("lets the agent read the host's chat attachment store, outside the workspace", async () => {
+    const launch = await resolverFor(
+      record(),
+      undefined,
+      false,
+      { claude: '' },
+      async () => true,
+      undefined,
+      '/state/agent-session-attachments'
+    )({ identity: IDENTITY })
+
+    expect(launch.options.additionalDirectories).toEqual(['/state/agent-session-attachments'])
+    expect(launch.cwd).toBe('/repos/workspace-1')
+  })
+
+  it('grants the attachment store beside folders the saved Arguments add', async () => {
+    const launch = await resolverFor(
+      record(),
+      undefined,
+      false,
+      { claude: '' },
+      async () => true,
+      () => ['--add-dir', '/extra'],
+      '/state/agent-session-attachments'
+    )({ identity: IDENTITY })
+
+    expect(launch.options.additionalDirectories).toEqual([
+      '/extra',
+      '/state/agent-session-attachments'
+    ])
+  })
+
   it('builds on the supplied inherited env instead of Orca process env', async () => {
     const launch = await createClaudeStructuredLaunchResolver({
       resolveLaunchArgs: () => [],

src/main/claude/claude-structured-launch-resolution.ts

@@ -1,5 +1,4 @@
 import { getClaudeProfileRouter } from '../claude-accounts/claude-profile-installed-router'
-import { createHash } from 'node:crypto'
 import type {
   Options as ClaudeAgentSdkOptions,
   PermissionMode
@@ -44,6 +43,9 @@ import type { ClaudeThinkingDisplaySupport } from './claude-thinking-display-sup
 import type { AgentSessionRecordStore } from '../runtime/agent-session-record-store'
 import { resolveAgentSessionLaunchDirectory } from '../runtime/agent-session-launch-directory'
 import { CLAUDE_STRUCTURED_AGENT } from './claude-structured-agent-definition'
+import { claudeSessionIdForOrcaSession } from './claude-structured-session-id'
+
+export { claudeSessionIdForOrcaSession }
 
 export const CLAUDE_DEFAULT_SETTING_SOURCES = ['user', 'project', 'local'] as const
 export const CLAUDE_SESSION_STATE_EVENTS_ENV = 'CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS'
@@ -135,6 +137,9 @@ export type ClaudeStructuredLaunchResolverDeps = {
   authSwitchSettleTimeoutMs?: number
   /** Account state for the managed-account gate; null when it cannot be read, which refuses. */
   readManagedAccountGate?: () => ClaudeManagedAccountGateSettings | null
+  /** The host's chat attachment store: files a client attached live there, outside the workspace,
+   *  and the agent reads them without asking. */
+  attachmentDirectory?: string
   /** Whether this CLI takes the thinking-display flag. Absent ⇒ the flag is never passed. */
   thinkingDisplay?: Pick<ClaudeThinkingDisplaySupport, 'argsFor'>
   /** Whether Claude wrote a transcript for this id; defaults to the transcript resolver. */
@@ -198,14 +203,6 @@ export async function assertClaudeAuthSwitchSettled(
   }
 }
 
-export function claudeSessionIdForOrcaSession(sessionId: string): string {
-  const bytes = createHash('sha256').update(`orca-claude:${sessionId}`).digest().subarray(0, 16)
-  bytes[6] = ((bytes[6] ?? 0) & 0x0f) | 0x40
-  bytes[8] = ((bytes[8] ?? 0) & 0x3f) | 0x80
-  const hex = bytes.toString('hex')
-  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`
-}
-
 export function createClaudeStructuredLaunchResolver(
   deps: ClaudeStructuredLaunchResolverDeps
 ): (input: { identity: AgentSessionJournalIdentity }) => Promise<ClaudeStructuredLaunch> {
@@ -265,7 +262,11 @@ export function createClaudeStructuredLaunchResolver(
       env: claudeProbeEnv(sources)
     })
     const configured = claudeStructuredLaunchArgs(await deps.resolveLaunchArgs())
-    const { additionalDirectories } = configured
+    // The user's own --add-dir folders, plus the host's chat attachment store.
+    const additionalDirectories = [
+      ...configured.additionalDirectories,
+      ...(deps.attachmentDirectory ? [deps.attachmentDirectory] : [])
+    ]
     const permission = claudeStructuredPermissionOptions(
       (await deps.resolvePermissionMode?.()) ?? 'default'
     )

src/main/claude/claude-structured-session-id.ts

@@ -0,0 +1,10 @@
+import { createHash } from 'node:crypto'
+
+/** A stable UUID (v4 layout) for the Claude conversation behind an Orca chat. */
+export function claudeSessionIdForOrcaSession(sessionId: string): string {
+  const bytes = createHash('sha256').update(`orca-claude:${sessionId}`).digest().subarray(0, 16)
+  bytes[6] = ((bytes[6] ?? 0) & 0x0f) | 0x40
+  bytes[8] = ((bytes[8] ?? 0) & 0x3f) | 0x80
+  const hex = bytes.toString('hex')
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`
+}

src/main/ipc/agent-session-attachment-upload-ipc.ts

@@ -0,0 +1,36 @@
+import { app, ipcMain } from 'electron'
+import type {
+  AgentSessionAttachmentPathUploadResult,
+  AgentSessionAttachmentUploadTarget
+} from '../../shared/agent-session-attachments'
+import { resolveEnvironment } from '../../shared/runtime-environment-store'
+import { uploadExternalPathsToAgentSessionAttachments } from './agent-session-attachment-upload'
+import { abortWhenRendererGone } from './renderer-lifetime-abort'
+
+export function registerAgentSessionAttachmentUploadHandlers(): void {
+  ipcMain.handle(
+    'fs:uploadPathsToAgentSessionAttachments',
+    async (
+      event,
+      args: AgentSessionAttachmentUploadTarget & { paths: string[] }
+    ): Promise<AgentSessionAttachmentPathUploadResult> => {
+      const userDataPath = app.getPath('userData')
+      // Why: a reload or close must stop the transfer; the server sweeps the part file it leaves.
+      const lifetime = abortWhenRendererGone(event.sender)
+      try {
+        return await uploadExternalPathsToAgentSessionAttachments(
+          {
+            ...args,
+            // The manual-disconnect check keys on the resolved id, not whatever selector came in.
+            environmentId: resolveEnvironment(userDataPath, args.environmentId).id,
+            userDataPath,
+            signal: lifetime.signal
+          },
+          args.paths
+        )
+      } finally {
+        lifetime.dispose()
+      }
+    }
+  )
+}

src/main/ipc/agent-session-attachment-upload.test.ts

@@ -0,0 +1,166 @@
+import { mkdir, mkdtemp, readFile, rm, symlink, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { AgentSessionAttachmentStore } from '../native-chat/agent-session-attachments/agent-session-attachment-store'
+
+type CallOptions = { expectedEnvironmentRuntimeId?: string; signal?: AbortSignal }
+type Call = {
+  method: string
+  params: Record<string, unknown>
+  revision?: number
+  options?: CallOptions
+}
+
+const calls: Call[] = []
+let serverStore: AgentSessionAttachmentStore
+let failMethod: string | null = null
+
+// The paired server, played by a real store: every call answers as the RPC handler would.
+vi.mock('./runtime-environment-transport-routing', () => ({
+  callRuntimeEnvironment: async (
+    _userDataPath: string,
+    _environmentId: string,
+    method: string,
+    params: Record<string, unknown>,
+    _timeoutMs?: number,
+    revision?: number,
+    _envelope?: unknown,
+    options?: CallOptions
+  ) => {
+    calls.push({ method, params, revision, options })
+    if (method === failMethod) {
+      return { ok: false, error: { code: 'internal', message: `${method} failed` } }
+    }
+    const callerKey = 'client-a'
+    const uploadId = String(params.uploadId)
+    try {
+      const result =
+        method === 'agentSessionAttachment.uploadStart'
+          ? await serverStore.startUpload({
+              callerKey,
+              sessionId: String(params.sessionId),
+              name: String(params.name),
+              byteLength: Number(params.byteLength)
+            })
+          : method === 'agentSessionAttachment.uploadAppend'
+            ? await serverStore.appendChunk({
+                callerKey,
+                uploadId,
+                offset: Number(params.offset),
+                contentBase64: String(params.contentBase64)
+              })
+            : method === 'agentSessionAttachment.uploadCommit'
+              ? await serverStore.commitUpload({ callerKey, uploadId })
+              : await serverStore.abortUpload({ callerKey, uploadId })
+      return { ok: true, result }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      return { ok: false, error: { code: 'internal', message } }
+    }
+  }
+}))
+
+const { uploadBufferToAgentSessionAttachments, uploadExternalPathsToAgentSessionAttachments } =
+  await import('./agent-session-attachment-upload')
+
+let workDir: string
+const context = () => ({
+  environmentId: 'env-1',
+  sessionId: 'session-1',
+  expectedEnvironmentPairingRevision: 7,
+  expectedEnvironmentRuntimeId: 'runtime-a',
+  userDataPath: join(workDir, 'client-user-data')
+})
+
+beforeEach(async () => {
+  workDir = await mkdtemp(join(tmpdir(), 'orca-attachment-upload-'))
+  serverStore = new AgentSessionAttachmentStore(
+    join(workDir, 'server', 'agent-session-attachments'),
+    { hasSession: () => true }
+  )
+  calls.length = 0
+  failMethod = null
+})
+
+afterEach(async () => {
+  serverStore.clearInFlightForTests()
+  await rm(workDir, { recursive: true, force: true })
+})
+
+describe('uploadExternalPathsToAgentSessionAttachments', () => {
+  it('uploads dropped files in order and returns only server paths', async () => {
+    const big = Buffer.alloc(1024 * 1024, 7)
+    await writeFile(join(workDir, 'big.bin'), big)
+    await writeFile(join(workDir, 'notes.md'), '# hi')
+
+    const result = await uploadExternalPathsToAgentSessionAttachments(context(), [
+      join(workDir, 'big.bin'),
+      join(workDir, 'notes.md')
+    ])
+
+    expect(result.skipped).toEqual([])
+    expect(result.failed).toEqual([])
+    expect(result.uploaded.map(({ sourcePath }) => sourcePath)).toEqual([
+      join(workDir, 'big.bin'),
+      join(workDir, 'notes.md')
+    ])
+    for (const { path } of result.uploaded) {
+      expect(path.startsWith(serverStore.rootDir)).toBe(true)
+    }
+    expect(await readFile(result.uploaded[0].path)).toEqual(big)
+    expect(await readFile(result.uploaded[1].path, 'utf8')).toBe('# hi')
+  })
+
+  it('pins every call to the pairing and every call to the server process', async () => {
+    await writeFile(join(workDir, 'a.txt'), 'a')
+    await uploadExternalPathsToAgentSessionAttachments(context(), [join(workDir, 'a.txt')])
+    expect(calls.map((call) => call.method)).toEqual([
+      'agentSessionAttachment.uploadStart',
+      'agentSessionAttachment.uploadAppend',
+      'agentSessionAttachment.uploadCommit'
+    ])
+    for (const call of calls) {
+      expect(call.revision).toBe(7)
+      expect(call.options?.expectedEnvironmentRuntimeId).toBe('runtime-a')
+    }
+  })
+
+  it('skips a folder as unsupported without walking into it', async () => {
+    await mkdir(join(workDir, 'folder', 'nested'), { recursive: true })
+    await writeFile(join(workDir, 'folder', 'inside.txt'), 'x')
+    // A link inside would make the stager skip the folder as a symlink: never reached.
+    await symlink(join(workDir, 'folder', 'inside.txt'), join(workDir, 'folder', 'nested', 'link'))
+    const result = await uploadExternalPathsToAgentSessionAttachments(context(), [
+      join(workDir, 'folder')
+    ])
+    expect(result.skipped).toEqual([{ sourcePath: join(workDir, 'folder'), reason: 'unsupported' }])
+    expect(calls).toEqual([])
+  })
+
+  it('aborts a failed upload on the server and reports the file as failed', async () => {
+    await writeFile(join(workDir, 'a.txt'), 'a')
+    failMethod = 'agentSessionAttachment.uploadCommit'
+    const result = await uploadExternalPathsToAgentSessionAttachments(context(), [
+      join(workDir, 'a.txt')
+    ])
+    expect(result.uploaded).toEqual([])
+    expect(result.failed).toEqual([
+      { sourcePath: join(workDir, 'a.txt'), reason: 'agentSessionAttachment.uploadCommit failed' }
+    ])
+    expect(calls.at(-1)?.method).toBe('agentSessionAttachment.uploadAbort')
+  })
+})
+
+describe('uploadBufferToAgentSessionAttachments', () => {
+  it('stores a pasted image under the chat', async () => {
+    const png = Buffer.alloc(900 * 1024, 3)
+    const stored = await uploadBufferToAgentSessionAttachments(context(), 'orca-paste-1.png', png)
+    expect(stored.name).toBe('orca-paste-1.png')
+    expect(await readFile(stored.path)).toEqual(png)
+    // 900 KiB in 384 KiB slices.
+    expect(
+      calls.filter((call) => call.method === 'agentSessionAttachment.uploadAppend')
+    ).toHaveLength(3)
+  })
+})