[Feature] Support image and file attachments in agent chat composers

[s7952452]

Problem

Paca now allows agents to read attachments that already belong to a task through read_task_attachment (#391). However, the agent chat composers themselves are still text-only.

On Paca v0.12.5, neither of these surfaces allows users to paste, drag and drop, or select an image/file:

• the agent chat inside a project;
• the standalone agent conversation page.

For screenshot-driven bug reports, test feedback, scanned materials, and requirement discussions, users must leave the conversation, upload the file to a task first, then return and tell the agent to read that task attachment. This breaks the natural chat workflow and is especially difficult for non-technical users.

This request is separate from #391: #391 covers agents reading existing task attachments; this request covers users attaching files to an agent-chat message.

Expected behavior

Agent chat composers should support:

• pasting images from the clipboard;
• dragging and dropping files;
• selecting one or more files through an attachment button;
• previewing/removing attachments before sending;
• displaying sent attachments in conversation history;
• sending the user's text and attachment references together as one logical message/turn;
• making attachments available to the agent in the same turn.

For a conversation linked to a task, uploaded files should preferably become attachments of that task rather than creating a second isolated file store. For a standalone conversation, Paca should persist the files against the conversation/message and enforce the same permission and storage controls.

Suggested design

1. Add a shared attachment-capable composer to both project chat and conversation pages.
2. Upload files before sending the message and represent them as structured message attachment references, not base64 embedded in normal text. Preserve the user's text and ordered attachment references as one logical message so downstream tools can analyze each file in the context of the user's actual question.
3. Every attachment reference should include at least a stable ID, scope (task or conversation), file name and MIME type in model-visible structured/text context. A text-only primary model must still be able to discover the attachment and call a configured OCR/vision/document-analysis tool instead of receiving an invisible image-only block.
4. When task_id is present, store/reuse the file as a normal task attachment so it remains part of the durable work item.
5. For standalone conversations without a task ID, expose a permission-aware conversation-attachment read path equivalent to read_task_attachment, so OCR/vision/document-analysis MCP tools can consume the file by ID without arbitrary URL access.
6. Include the new attachment references in the current agent turn and allow the agent to consume them through the existing permission-aware attachment path introduced by [Feature] Let agents securely read task attachments, including text and images #391.
7. Detect model capabilities:
   • pass images to vision-capable models;
   • for text-only models, return a clear limitation or use an explicitly configured OCR/vision proxy;
   • never silently discard an attachment.
8. Enforce file count, size, MIME type, quota, malware/security checks, and project/task permissions.
9. Keep conversation history bounded by storing durable references instead of repeatedly embedding large image payloads.

Acceptance criteria

• A user can paste a PNG screenshot directly into the project agent chat, add text, and send both in one message.
• Drag/drop and file-picker upload work for common image and text/code formats.
• The attachment is visible in conversation history and remains available after reloading the page.
• The agent receives the user's text and all attachment references as the same logical turn, preserving their relationship and order.
• The agent can read the text attachment during that turn.
• With a vision-capable model, the agent can describe or extract visible text from the image.
• With a text-only primary model, attachment metadata/references remain model-visible and the agent can call a configured OCR/vision/document-analysis tool using the user's accompanying text as the analysis question. If no such tool is configured, the UI/agent clearly reports the limitation instead of ignoring the image.
• In a task-linked conversation, the uploaded file is associated with the task and can later be read through read_task_attachment.
• A standalone conversation attachment can be read by ID through a permission-aware API/tool path without requiring a task or exposing an arbitrary storage URL.
• The feature works consistently in both the project chat panel and standalone conversation page.
• Users without access to the owning project/task/conversation cannot access the file.

Related issues

• [Feature] Let agents securely read task attachments, including text and images #391 — agent-side reading of existing task attachments
• [Feature] Task-level agent conversation continuity across terminal sessions and closed tasks #392 — durable task-level continuity across separate conversations

[pullfrog]

  ^{｜ Build this ➔ ｜ Make a plan ➔}

[s7952452]

I would be interested in taking ownership of this feature if the proposed boundary matches Paca's upstream direction.

My suggested responsibility boundary is:

• Paca core owns upload, permission-aware storage, durable attachment references, and conversation history;
• task-linked conversations reuse normal task attachments and the existing read_task_attachment path;
• standalone conversations use conversation-scoped attachments with an equivalent permission-aware read path;
• user text and ordered attachment references remain one logical turn;
• vision, OCR, and document analysis are supplied by the configured model or external tool rather than being hard-coded into Paca core;
• text-only primary models still receive model-visible attachment IDs, names, MIME types, and scopes so they can call configured tools; attachments must never be silently discarded.

Because this spans the frontend, message protocol, storage, permissions, and agent input, I can first post a code-level implementation plan and then keep the PRs focused. A possible sequence is:

1. task-linked chat attachments;
2. standalone conversation attachments;
3. multimodal-model and external analysis-tool integration refinements.

Would this direction be acceptable, and may I take ownership of the issue?

[pikann]

Hi @s7952452

Awesome! I've assigned the issue to you. Thanks a lot for taking this on!

Just a quick note: please be aware that I'm working on a big update on master to migrate our agent setup from OpenHands to Goose for better performance and smaller container sizes.

Feel free to share the implementation plan whenever you're ready!

[s7952452]

Thanks for the note about the Goose migration. I rechecked the latest upstream/master against the current Goose/ACP paths and also reviewed how this feature relates to #392. My conclusion is that #397 and #392 should share the same session, turn, context, authorization, and delivery foundations, while retaining separate acceptance criteria and reviewable PRs rather than being treated as duplicate issues.

User-facing behavior

I propose supporting three entry paths.

1. Start a chat without a task

A chat started from the global or project home creates an owner-private chat session:

• Pasted screenshots, images, and one or more files are added to a pending attachment list rather than sent immediately or inserted as local paths.
• Normal file selection is supported, with drag-and-drop as an additional input when it fits the existing composer.
• Images show previews. Other files show name, MIME type, size, and upload state.
• Attachments can be removed or retried in place without changing the order of the remaining files.
• Text and ordered attachment references are sent and persisted atomically as one logical message/turn.
• Refreshing or reopening the chat restores the same attachment history and session scope.

These attachments remain session-scoped and owner-private.

2. Start a chat from a task

The task page gets an explicit Start chat action that creates an owner-private task-bound session:

• The session's project, task, agent, owner, and audience are immutable after creation.
• Goose receives a bounded task context pack: core task fields, the current trigger, relevant handoffs, an attachment manifest, and explicit truncation information.
• Newly uploaded files become normal task attachments when the message is successfully sent and remain readable through the existing read_task_attachment path.
• Selecting existing task attachments in the composer can be added incrementally, but the model should receive the existing task attachment manifest from the first version.
• The transcript is owner-private, while task attachments are task-shared. The composer must make that visibility difference explicit before sending.

3. Resume a chat from history

The Chats history restores the original chat session, not merely the most recent runtime conversation:

• A task-bound session continues with its task context and task attachment scope.
• A taskless session continues with its session attachment scope.
• Scope and audience are never inferred again from the page the user happens to be viewing.
• If the Goose/ACP runtime can be resumed safely, it may be reused. Otherwise the session creates a new runtime conversation and restores bounded context.

The existing Conversations/Runs surface also contains assignment, comment mention, automation, and Write with AI executions. It should not be replaced by a Chats-only view. I propose keeping Runs/audit history and existing permalinks, while adding Chats/session history as a separate projection.

Comment mentions, assignments, automations, and Write with AI remain sessionless runs. Continue as chat from one of those runs creates a new task-bound session and a new owner-private runtime conversation that references the source run/turn; it does not rebind the old shared conversation.

Shared execution model

I propose making the following boundaries explicit:

• task: durable business context.
• chat_session: the durable user-visible thread restored from Chats history.
• agent_conversation: a Goose/ACP runtime continuity segment that may span multiple turns and may be replaced while the chat session continues.
• agent_turn: one user input or system trigger through one stable result; this is the authoritative execution unit.

turn_id should flow through the canonical input event, ordered attachments, trigger/outbox, runner claim, ACP start-turn protocol, streaming events, watchdog, realtime, stable result, and #392 handoff.

agent_turn.status/result is authoritative for an execution. Conversation status only indicates whether a runtime segment is reusable, busy, or no longer available. Handoff must not be inferred from a conversation becoming terminal. Session history receives a monotonic session_turn_index so ordering remains stable across multiple runtime conversations.

Task handoff semantics for #392

I recommend distinguishing two cases:

• A successful sessionless task run automatically creates an idempotent task-shared handoff.
• A turn in an owner-private task chat does not automatically publish its response. The user explicitly chooses Publish handoff or Share result, previews a bounded summary, and then publishes that summary to the task.

Publishing copies only the confirmed shared summary. source_turn_id and final_event_id provide provenance and idempotency but do not grant task readers access to the private transcript. The publication records published_by, published_at, source identifiers, and the shared audience.

Message and upload lifecycle

The composer generates and reuses a client_message_id for each logical send:

• Repeating the same key with the same text and ordered attachments returns the existing turn.
• Reusing the key with different content or order returns 409.
• A session has an explicit single-active-turn or queue policy rather than relying on request races.
• Sending is blocked while any attachment is still uploading or failed, with a clear retry path.

I propose extending the existing file lifecycle as the single upload-intent authority, with an immutable origin scope, uploader, expected metadata, attempt, expiry, and staging key. A recoverable state machine can be:

pending -> uploaded -> verifying -> finalizing -> complete
                                \-> failed

Presigned PUT only targets staging. Complete revalidates the uploader, current membership/RBAC, task or session scope, actual size, MIME/magic, checksum or object version, attempt, and expiry. The verified object is copied to a deterministic immutable final key or pinned version that is never exposed through PUT.

Because object finalization and the database association are not a single transaction, retries must recover from a crash after copy but before database commit by inspecting the deterministic final object. Finalizing needs a lease/reaper, and expired staging objects, failed uploads, orphan final objects, unused drafts, and tombstones need cleanup workers.

Removing an item from the composer removes only the draft reference. A draft-only unreferenced upload can be cleaned asynchronously; a sent or task-associated file is not hard-deleted by the composer.

Ordered event attachment records should reference exactly one real task_attachment_id or chat_attachment_id. Display metadata in JSON is only a historical snapshot and never an authorization source. Cross-model scope invariants should be enforced by database constraints and transactional conditional writes, not only service-layer prechecks.

If an attachment is later deleted, history should retain its name/type/size and show an unavailable tombstone rather than silently changing the original message. Read authorization continues to follow the original task or session scope.

Model and Goose input

Every model, including a text-only primary model, receives the ordered attachment manifest:

• stable attachment ID;
• file name;
• MIME type and actual size;
• order and task/session scope;
• availability state;
• the permitted read tool.

Persistent events contain neither binary data nor short-lived signed URLs. Task content, file names, and extracted attachment content are marked as untrusted external input.

Native image input may be added after real Goose/provider validation, but it is an enhancement rather than the condition for preserving attachments. Paca does not need to hard-code OCR, PDF, or Office parsing; configured models or external tools can supply those capabilities.

Authorization and execution capability

I propose the following audience model:

Source	Transcript	Attachments/results
Global taskless chat	owner-private	session-private
Project taskless chat	owner-private	session-private
Task-bound chat	owner-private	new attachments are task-shared; explicitly published handoffs are task-shared
Sessionless task run	task/project-shared	automatic handoff is task-shared
Sessionless project audit run	project-shared	project-shared

The same audience policy must govern list/get/search, events/history, send/control, realtime, uploads/downloads, and MCP tools. Owner-private traffic must use a user-scoped realtime channel and must not also be broadcast to the project room.

During review I found inconsistent scope enforcement in existing conversation access. This should be unified before attachment metadata is exposed. I am intentionally not including actionable security details in a public issue and can provide them through a maintainer-approved private channel.

The hosted runner/MCP boundary also needs a short-lived per-turn execution capability bound to turn, attempt/fencing generation, conversation, session, agent, actor user/member, project, task, and expiry. Each API/MCP call still rechecks current membership and RBAC; a capability cannot preserve access after permission revocation. A shared API key plus caller-declared identity or scope headers is not a sufficient attachment authorization boundary.

There is a real implementation question here: central Goose and local ACP can reuse a process across turns, while a fixed process environment cannot safely keep using an earlier turn's capability. I propose a real protocol spike before the attachment PR:

1. Prefer a runner/bridge-controlled trusted credential refresh so runtime continuity can be preserved.
2. If that cannot be demonstrated safely for a path, create a new runtime conversation for each scoped turn on that path and restore a bounded context pack.
3. Never fall back to a shared credential, model-declared scope, or a path that silently drops attachments.

For local ACP, the preferred result is the same dynamic MCP capability and read tools. If the protocol cannot support it, a trusted bridge may stage only the authorized turn's files in an isolated per-turn temporary directory, with current authorization checks, a stable manifest, no durable local-path references, and cleanup on completion/cancellation/expiry.

Delivery reliability and compatibility

The send transaction should atomically validate the session, allocate the session turn index, create the turn and canonical user event, attach the ordered references, activate the draft session, and write a transactional outbox record. Valkey is transport; the database turn is authoritative.

Runner claims use a lease plus an increasing attempt_no/fencing token. A reclaimed turn rejects late heartbeat, event, status, MCP write, and final-result writes from an older attempt. MCP write tools propagate a stable (turn_id, tool_call_id) idempotency key where possible.

On success, one PostgreSQL transaction verifies the current attempt, writes the complete stable final event/result, updates the turn, and writes the completion outbox. A missing streaming chunk must not produce a successful turn without a stable final result. Pending reclaim, retry, dead-letter handling, and a user-visible safe retry state are required.

During rolling deployment, the new runner should accept both legacy flat triggers and versioned v2 turn triggers. When turn_id is present, the database turn is authoritative. Legacy event turn_id remains nullable rather than guessing historical turn boundaries.

For existing data, I propose that session-backed project conversations inherit the session owner and become owner-private; sessionless task/project runs keep their shared audit audience. Rows whose owner/scope cannot be determined are quarantined/fail closed and reported by the migration. Existing permalinks remain valid under the corrected audience policy.

Proposed PR sequence

I propose reviewable stacked changes:

1. Turn/outbox/audience authorization, realtime isolation, fencing, and legacy trigger compatibility.
2. [Feature] Task-level agent conversation continuity across terminal sessions and closed tasks #392: bounded context and idempotent handoff for existing sessionless task runs.
3. Task-bound sessions, Chats/history, Start chat, and Continue as chat.
4. [Feature] Support image and file attachments in agent chat composers #397: upload lifecycle, composer/history UX, MCP/capability, and real Goose/ACP E2E validation.

If the capability work requires a substantial runner/ACP change, it can be a focused foundation PR 1b, but it remains a hard prerequisite for the complete #397 experience.

The validation matrix will include paste/select/drop for one or many images/files; text and attachment ordering; removal/retry/limits/unsupported formats; taskless/task-bound/history flows; duplicate and tampered requests; incomplete uploads and finalize crash recovery; cross-user/project/task/session denial; membership removal; realtime isolation; outbox duplication and runner reclaim; private-versus-published handoffs; text-model manifests; real central Goose and local ACP attachment reads; populated legacy DB upgrades; required unit/integration/frontend/E2E tests; and a real local Paca smoke test.

Recommendations that need maintainer confirmation

1. Task-chat handoff: I recommend automatic handoff for successful sessionless task runs, but explicit user-reviewed publication for owner-private task chat. This avoids leaking every private turn while still giving [Feature] Task-level agent conversation continuity across terminal sessions and closed tasks #392 a durable shared result. Does this match the intended product behavior?

2. Audience and Continue as chat: I recommend making all session-backed project chats owner-private and always creating a new private runtime conversation when continuing from a shared run. This prevents a single event stream from mixing shared and private audiences while preserving old run permalinks. Is this visibility migration acceptable?

3. Capability versus runtime reuse: I recommend first testing trusted per-turn credential refresh, but falling back to a new runtime conversation plus bounded context when refresh cannot be proven safe. Authorization boundaries should take priority over in-place runtime continuity. Is that fallback acceptable?

4. Local ACP: I recommend dynamic MCP capability as the primary design, with strictly isolated trusted bridge staging only when the ACP protocol cannot support secure refresh. This keeps central/local semantics aligned without inventing caller-declared scope. Is this acceptable?

5. Removal/deletion: I recommend draft-reference removal, cleanup of unreferenced draft files, and tombstoned historical metadata after a sent attachment is deleted, with read access always following the original task/session scope. This avoids accidental task-asset deletion and silent history changes. Does this match the expected UX?

6. PR order: I recommend the four-stage dependency above, with an optional focused capability foundation PR. This lets [Feature] Task-level agent conversation continuity across terminal sessions and closed tasks #392 ship on the reliable turn foundation without waiting for the complete attachment UI and avoids an unreviewable cross-stack PR. Is this sequencing acceptable?

Once these boundaries are confirmed, I can finalize the migrations and implementation/test plan against them.

[pikann]

Thanks for the detailed breakdown!

Overall, the proposed changes look good. Since this is a big structural shift in the system, we'll need to make sure everything is thoroughly tested before releasing it.

Regarding image and file attachments, it would be ideal to allow toggling this feature on/off and configuring which models execute it. Some models (like Claude Code) can already process images natively, so having control over this avoids unnecessary processing when it's not needed.

Thanks a lot for putting so much effort into this! 🙌

[pikann]

By the way, feel free to connect with me on LinkedIn (linkedin.com/in/pikann22) if you’d like to discuss this further or brainstorm implementation details!

[s7952452]

Thanks @pikann — the toggle + per-model configuration makes sense, I'll fold it into the design (operators can enable/disable attachment handling and pick which models process files, avoiding redundant processing when a model like Claude Code already handles images natively).

Before writing code I'd like to lock the PR split, since this spans backend, frontend, MCP and migrations:

1. Security/audience fix first, as its own PR. While reviewing I found inconsistent scope enforcement in the existing conversation-access path. Unifying it (owner-private / task-shared / project-shared audiences + realtime isolation) is hardening of existing behavior, not new functionality, and should land before attachment metadata is exposed. I'd keep this a separate, independently testable PR, and can share the specifics through a private channel rather than the public issue.
2. Then one PR per issue. [Feature] Task-level agent conversation continuity across terminal sessions and closed tasks #392 (durable handoff, including the turn/outbox/fencing plumbing it needs) and [Feature] Support image and file attachments in agent chat composers #397 (sessions/Chats + upload lifecycle + composer + the toggle/config), each independently reviewable and smoke-testable.

Does that split work for you? Main goal is to avoid one huge cross-stack PR while your Goose migration is in flight — happy to adjust.

[pikann]

Hi @s7952452 ,
Makes total sense! Thanks again for the clear breakdown, looking forward to the PRs.