Feature Spec: Cloud Drive Integration Model

Document ID: FS-2026-001 Owner: Product Manager Date: 2026-02-18 Status: Draft Product: Legionis V2V Phase: Phase 3 (Strategic Commitments) Related: PRD V3.0, DR-2026-002 (Cloud Storage First), Architecture Stack V1.4, Execution Plan V3.1

1. Overview

Legionis currently provides a Drive-backed workspace where agents read and write files within a dedicated folder structure. This feature expands the integration model so users can browse their entire Google Drive from within Legionis, drag files into the chat console to give agents context, and manage files anywhere in their Drive without leaving the platform. The single restriction: agents create new deliverables exclusively in the Legionis workspace folders. This turns Legionis from a workspace-scoped tool into a full Drive companion that respects the user's ownership of their files while maintaining a clean boundary for agent output.

2. Product Decision

The agreed model has four pillars:

The principle: "The Drive is theirs, Legionis is a guest."

This means: users have full sovereignty over their Drive. Legionis never restricts what they can see, touch, or organize. The platform only constrains where its own agents deposit work product, keeping the workspace clean and predictable.

3. User Stories

US-001: Browse Full Drive

As a Legionis user I want to browse my entire Google Drive from within Legionis So that I can find and reference any file without switching to another tab

Acceptance Criteria:

• Given I am in the file explorer, when I toggle to Drive view, then I see my full Google Drive folder tree starting from root
• Given I am in Drive view, when I expand a folder, then its contents load and display (files and subfolders)
• Given I navigate deep into my Drive, then breadcrumbs show my current location and allow quick navigation back

US-002: Drag File into Chat

As a user preparing instructions for an agent I want to drag a file from the file explorer into the chat input area So that the agent receives that file's content as context for my request

Acceptance Criteria:

• Given I drag a file over the chat input area, then a visual drop zone indicator appears (highlighted border)
• Given I drop a supported file (.md, .txt, .pdf, .docx, .csv, .json, .html), then it appears as a removable chip below the chat input
• Given I drop a Google Doc/Sheet/Slides file, then it is auto-exported to a text format and attached as a chip
• Given I send a message with attached files, then the agent receives the file contents prepended to my message

US-003: Manage Files Across Drive

As a user organizing my work I want to move, rename, and organize files anywhere in my Drive from within Legionis So that I can keep my Drive tidy without leaving the platform

Acceptance Criteria:

• Given I right-click a file in Drive view, then I see context menu options: Rename, Move, Delete (Trash), Download, Open in Google Drive
• Given I select Rename and enter a new name, then the file is renamed in Google Drive
• Given I drag a file to a different folder in Drive view, then the file is moved to that folder
• Given I select Delete, then the file moves to Google Drive trash (not permanently deleted)

US-004: Agent Deliverable Goes to Workspace

As a user who asked an agent to create a document I want the output to land in my Legionis workspace folder So that agent-generated work is organized and predictable

Acceptance Criteria:

• Given I ask an agent to create a PRD, when the agent saves the file, then it is saved to {workspace}/deliverables/
• Given I ask an agent to "save this to my Marketing folder", then the agent saves to workspace and suggests: "I've saved this to your workspace deliverables folder. You can move it to your Marketing folder from the file explorer."
• Given an agent attempts to write outside the workspace, then the write operation is rejected by the tool boundary

US-005: Reference Non-Workspace File

As a user giving an agent background material I want to attach a file from outside my workspace to the conversation So that the agent can use existing documents as context without me copying them into the workspace

Acceptance Criteria:

• Given I click the attachment button (paperclip icon) in the chat input, then a Drive file picker opens showing my full Drive
• Given I select a file from the picker, then it appears as an attached chip in the chat input
• Given I send the message, then the agent can read the attached file's content and reference it in its response

US-006: Quick Return to Workspace

As a user who browsed deep into my Drive I want to return to the Legionis workspace view with one click So that I can quickly switch between Drive browsing and workspace focus

Acceptance Criteria:

• Given I am in Drive view, when I click the "Workspace" toggle/button, then the explorer immediately shows the workspace tree (current behavior)
• Given I am in Drive view, then the Legionis workspace folder is visually distinguished with an accent color and pin icon
• Given I click the pinned workspace folder in Drive view, then it expands to show the workspace contents inline

US-007: Attach Multiple Files

As a user preparing a complex request I want to attach multiple files from different Drive locations to a single message So that the agent has all the context it needs in one go

Acceptance Criteria:

• Given I have already attached one file, when I drag or pick another file, then both appear as chips below the chat input
• Given I have multiple files attached, when I click the X on a chip, then that file is removed from the attachments
• Given I send a message with 3 attached files, then the agent receives all three file contents as context

US-008: Create Folder in Drive

As a user organizing my Drive I want to create new folders anywhere in my Drive from within Legionis So that I can set up folder structures without switching apps

Acceptance Criteria:

• Given I right-click a folder in Drive view, when I select "New Folder", then a new folder is created inside it
• Given I create a new folder, then the explorer refreshes to show it immediately

4. UX Specification

4.1 File Explorer (Updated)

The file explorer component (file-tree.tsx) gains two modes controlled by a toggle at the top of the panel.

Mode Toggle:

• A segmented control at the top of the file explorer: [Workspace] [Drive]
• Default mode: Workspace (current behavior, unchanged)
• Switching to Drive loads the user's full Google Drive tree from root
• The active mode is visually indicated with the primary accent color

• Identical to today's behavior. Shows the Legionis workspace tree starting from /
• The "Drive" button in the toggle serves as the entry point to full browsing

• Shows the user's entire Google Drive starting from root
• Folder hierarchy is lazy-loaded (children fetched on expand, same pattern as workspace view)
• The Legionis workspace folder is visually distinguished:

• Breadcrumb trail appears above the tree when navigating: My Drive / Projects / Q1 Reports

• Shared drives and "Shared with me" appear as top-level entries alongside "My Drive"

• The last-used mode (Workspace vs. Drive) persists across page navigations within a session
• Expanded folder state is preserved when switching between modes

4.2 Drag and Drop to Chat

Drag Initiation:

• Any file in the file explorer (either mode) can be dragged
• Drag handle is the entire file row (consistent with native file manager behavior)
• During drag, the cursor shows a file icon with the filename

• The entire chat input area (the message composer component) is a valid drop target
• When a file is dragged over the chat input, the input area shows:

• When the drag leaves the drop zone, the visual indicator fades out

• After a successful drop, the file appears as a chip/pill below the chat input and above the send button
• Chip format: [icon] filename.ext [x]

• Multiple chips stack horizontally with wrapping
• Maximum attachments per message: 10 files
• If a user tries to attach more than 10, show a toast: "Maximum 10 files per message"

Unsupported files:

• Binary files (.png, .jpg, .zip, .exe, etc.) show a toast: "This file type can't be shared with agents yet"
• Files larger than 500KB (after text extraction) are truncated with a notice prepended to the content: [Truncated: showing first 500KB of {filename}]

• When the user sends a message with attachments, the agent receives the message in this format:

[Attached: filename1.md]

[/Attached]
[Attached: filename2.pdf]

[/Attached]

4.3 File Management Actions

Context Menu (Right-Click):

In Drive view, right-clicking any file or folder surfaces a context menu with these actions:

Drag-to-Move within Explorer:

• In Drive view, users can drag files/folders to other folders to move them
• A blue insertion indicator shows the target folder during drag
• Drop triggers a Drive API files.update to change the parent

• The Legionis workspace folder and its contents are manageable (rename workspace subfolders, etc.)
• A warning appears if a user tries to trash the workspace root: "This is your Legionis workspace. Trashing it will disconnect your agent context. Continue?"

4.4 Chat Input Enhancement

The chat message composer gains three new interaction points:

Attachment Button:

• A paperclip icon (from lucide-react) positioned to the left of the send button
• Clicking it opens a Drive file picker modal (same component as "Move to..." but filtered to files)
• Selected file is added as an attached chip
• Button shows a badge count when files are attached: [paperclip][2]

• The entire chat input area (textarea + button bar) is a drop target
• Visual feedback as described in Section 4.2

• Cmd+K (or Ctrl+K) opens the command palette
• Typing "attach" or "file" surfaces: "Attach file from Drive"
• Selecting this action opens the same Drive file picker modal

• Cmd+Shift+A (or Ctrl+Shift+A) opens the Drive file picker directly

5. Agent Runtime Implications

5.1 Read Scope

Agent read access follows an explicit-consent model:

Agents never proactively browse the user's Drive. They only access files the user explicitly provides through drag-and-drop or the attachment picker. This is the trust model: the user decides what context the agent receives.

5.2 Write Boundary (THE RULE)

This is the single hard constraint in the entire integration model:

Agents can only write to the Legionis workspace.

When a user asks an agent to save outside the workspace:

The agent should:

This keeps agent behavior predictable while giving the user full control over final file placement.

5.3 New Agent Tools

readAttachedFile

readAttachedFile({
  fileId: string  // Google Drive file ID of the attached file
}): Promise

• Reads the content of a file the user attached to the current conversation
• Only works for file IDs that were explicitly attached in the current message or conversation
• Returns extracted text content (with conversion for PDF, DOCX, Google Workspace files)
• Returns an error if the file ID was not attached by the user (prevents agent from using arbitrary file IDs)

• readFile(path) resolves paths relative to workspace root (unchanged)
• writeFile(path, content) writes within workspace only (unchanged, boundary enforced)
• editFile(path, oldText, newText) edits within workspace only (unchanged)
• listDirectory(path) lists workspace directories (unchanged)
• globFiles(pattern) searches workspace files (unchanged)
• grepContent(pattern) searches workspace file contents (unchanged)

5.4 Attachment Lifecycle

Attachments are scoped to the conversation turn in which they are sent:

6. Technical Notes

6.1 OAuth Scope Change

The current OAuth configuration in src/lib/drive/auth.ts uses the drive.file scope:

const SCOPES = ["https://www.googleapis.com/auth/drive.file"];

The drive.file scope only grants access to files created by the application or explicitly opened by the user through the Google Picker. For full Drive browsing and file management, the scope needs to change.

Options:

Recommendation: Use https://www.googleapis.com/auth/drive (full access). This is necessary for: browsing all folders, reading user-selected files, moving/renaming files anywhere, and creating folders outside the workspace.

Migration path for existing users: Users who already connected their Drive with drive.file will need to re-authorize. On first use of the Drive browser feature, detect the insufficient scope and prompt: "To browse your full Drive, we need to update your permissions. [Reconnect Google Drive]". This triggers a new OAuth flow with the broader scope.

6.2 File Content Extraction

For non-plaintext files, a server-side extraction layer is needed:

This extraction runs server-side in the API route before passing content to the agent runtime.

6.3 File Size and Chunking

Large files need handling before they reach the agent context window:

• Soft limit: 500KB of extracted text per file
• Hard limit: 2MB raw file size (skip extraction, return error)
• Truncation: Files exceeding the soft limit are truncated with a header: [Truncated: showing first ~500KB of {N}KB file]
• Multiple attachments: Total attachment content capped at 2MB of extracted text across all files in a single message

6.4 API Routes (New)

Existing routes (/api/drive/files, /api/drive/files/content) remain for workspace-scoped operations.

6.5 Caching and Performance

• Folder listings: Cache Drive folder contents client-side for 60 seconds (stale-while-revalidate pattern via TanStack Query)
• File metadata: Cache file names, types, and IDs in memory during the session
• Invalidation: Any file management action (move, rename, delete, create) invalidates the cache for the affected parent folders
• Pagination: Drive API returns max 100 files per page. Implement cursor-based pagination for folders with many items (load more on scroll)

7. Privacy and Trust

This feature expands Legionis's access to the user's Drive. The trust contract must be explicit and verifiable.

What Legionis does:

• Displays the user's Drive folder structure when they open Drive view
• Reads file content only when the user explicitly attaches a file to a conversation
• Executes file management operations only when the user explicitly triggers them (right-click actions, drag-to-move)
• Saves agent deliverables only to the Legionis workspace folder

• No background scanning or indexing of the user's Drive
• No crawling of folder trees beyond what the user has expanded in the UI
• No caching of file contents beyond the current session
• No server-side storage of any Drive file content (content flows through to the AI provider via BYOT)
• No sharing of Drive metadata with third parties

• File content passed to agents goes through the user's own API key
• Legionis's server-side role is limited to: reading the file via Drive API, passing the text to the AI provider endpoint, and streaming the response back
• The content transits through Legionis infrastructure but is not stored, logged, or retained

"Legionis can browse your Google Drive to help you find and organize files. We only read file contents when you explicitly share them with your agents. Your files stay in your Drive. Agent work products are saved to your Legionis workspace folder."

Audit trail:

• Every file management action (move, rename, trash, create folder) is logged in the conversation where it occurred
• Attachment events are logged in the conversation turn metadata

8. Success Criteria

9. Out of Scope (v1)

The following are explicitly deferred to future iterations:

• Multi-cloud support: OneDrive, Dropbox, iCloud. Google Drive only for v1. Cloud abstraction layer is in the architecture but not yet implemented.
• File version history: Viewing previous versions of a file within Legionis. Users can use Google Drive's native version history via "Open in Google Drive."
• Collaborative editing: Real-time multi-user editing of files. Out of scope for the entire MVP.
• Drive search: Full-text search across the user's Drive from within Legionis. Users can search within the workspace (existing grep tool) or use Drive's native search. Typesense integration (planned for Week 8) covers workspace search.
• File preview in explorer: Previewing non-markdown files (PDF, images) inline in the file explorer panel. Markdown preview already exists in file-preview.tsx.
• Selective sync/favorites: Pinning frequently-used Drive folders for quick access (beyond the workspace pin).
• Batch operations: Selecting multiple files for bulk move/rename/delete.
• Offline access: Caching Drive files for offline use.

Appendix A: Current Implementation Reference

Files that will be modified:

Files that remain unchanged:

• src/lib/drive/client.ts (Drive client factory, already handles arbitrary operations)
• src/lib/drive/path-resolver.ts (workspace path resolution, still needed for workspace tools)
• src/lib/drive/workspace-init.ts (workspace folder creation, still needed for onboarding)
• src/tools/write-file.ts (workspace-scoped write, boundary already enforced)
• src/tools/edit-file.ts (workspace-scoped edit, boundary already enforced)

• pdf-parse (PDF text extraction)
• mammoth (DOCX text extraction)
• cheerio (HTML text extraction)

Appendix B: Drive API Scope Comparison

The drive scope is the only option that supports the full feature set. The trust contract (Section 7) and audit trail mitigate the broader access.