actus: advanced file and resource operations -- SSE tool results and agent-visible file context

[metasmile]

Summary

The Zed agent has powerful file and resource tools (read, write, search, grep, directory listing). Currently, actus only exposes file search/mention via REST. The agent's file operations and their results should be surfaced through SSE events so clients can see what the agent is doing.

Requirements

Expose agent tool results in SSE stream

• When the agent reads a file (read_file), the file content appears in the SSE stream with entry_type: "tool_call", tool_name: "read_file", tool_status: "completed"
• When the agent writes a file (write_file), the write confirmation appears as an SSE event
• When the agent runs a directory listing, results are streamed as SSE events
• When the agent searches/greps code, matches are streamed as SSE events
• When the agent runs a shell command, stdout/stderr is streamed as SSE events
• Each event carries metadata: tool_name, tool_status, resource_path, content_preview

Directory listing endpoint

• GET /v1/files/list?dir=src/ -- list directory contents (respect .gitignore)
• Returns FileEntry[] matching the existing search_files format
• Include file size, modified time, and MIME type for each entry

File read endpoint

• GET /v1/files/read?path=src/main.rs -- read file content as plain text
• Respect .gitignore (prevent reading files in ignored directories... though this is a soft gate)
• Respect binary file detection: refuse to read binary files, return { "binary": true, "mime_type": "..." }
• Optional range/line parameters: ?start=10&end=20

Resource mention SSE events

• When the Zed agent mentions a file path in its response, emit a dedicated SSE event resource.mention
• The event includes the resolved absolute path, relative path, and a content preview (first 5 lines)
• Client (CLI or UI) can use these events to display clickable file links
• Distinguish between agent-mentioned paths and user-mentioned paths (from @-mention)

Agent-visible file context

• The user should be able to attach file context to a message: POST /v1/chat with optional files: ["src/main.rs", ...]
• Server reads the files and injects their content into the prompt context before sending to Zed
• The Zed agent then has the file content available without needing to call read_file

API Design

GET /v1/files/list?dir=src/&max=100   # list directory
GET /v1/files/read?path=src/main.rs    # read file content
     optional: &start=10&end=20        # line range
     optional: &raw=true               # skip binary detection

SSE event types (in addition to existing message_added):

• tool.read_file.completed -- file read result
• tool.write_file.completed -- write confirmation
• tool.search.completed -- search/grep results
• tool.list_dir.completed -- directory listing
• tool.shell.completed -- shell command output
• resource.mention -- agent-mentioned file path

Current state

• GET /v1/files?q=&dir=&max= -- search files by name (exists)
• GET /v1/files/mention?q= -- mention-format file results (exists)
• MIME type detection in file search
• FileEntry struct with path, size, modified, mime_type

Related

• Part of actus: achieve Zed UI-level agent capability from native Rust server #1 (actus master epic)
• nexus #128 Section 4 (File and Resource Operations)

[metasmile]

Migrated from ssccsorg/nexus#130.