Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.
Python agent-orchestrationai-agentai-coding-assistantclaude-codecoding-agentcomputer-usedesktop-applocal-firstmcppersonal-jarvisvoice-assistantvoice-coding
"""Files dropped, pasted or picked into a chat composer.
The typed chats — the front page and the Agentic IDE's chat mode — take a
sentence and nothing else. Someone with a screenshot of a broken layout has to
describe it in words, which is the one thing a screenshot exists to avoid. The
IDE's TERMINAL panes have taken dropped files since 2026-08 (``drops`` +
``drop_analysis``); the chats were never wired to any of it, so a drop landed
on a bare ``<textarea>`` and the browser navigated away to the file.
This module is that wiring, and it is deliberately thin: everything hard was
already solved one layer down and is reused rather than rewritten.
* :mod:`dodaios.agentic_ide.drops` writes the bytes into the chat's own working
directory (``.jarvis/drops``, self-ignoring) and hands back a reference the
agent can open.
* :mod:`dodaios.agentic_ide.drop_analysis` has a vision-capable model describe
an image and extracts a document's text.
* :func:`dodaios.agentic_ide.prompt_blueprint.attachment_block` lays the result
out for whatever answers the turn.
Why the description travels with the message rather than the file alone: a
chat can be answered by a coding CLI, by a provider's own API loop, or by
Jarvis' brain, and several of those cannot open an image at all. Sending only
a path means the person drops a picture, types "what is wrong here", and the
model receives a filename and a pronoun. The description is what makes the
gesture work on every seat instead of the maintainer's.
Import-light on purpose (AP-26): the heavy halves are imported inside the
functions, so a boot that never sees an attachment pays nothing for this.
"""
from __future__ import annotations
import asyncio
import logging
from collections.abc import Sequence
from pathlib import Path
from typing import TYPE_CHECKING, Any
if TYPE_CHECKING:
from dodaios.agentic_ide.drops import DropSource
log = logging.getLogger(__name__)
__all__ = [
"AttachmentError",
"compose",
"ingest",
"to_analysis",
]
class AttachmentError(RuntimeError):
"""The attach carried nothing usable, or the copies could not be written."""
def handoff_context(cwd: str, attachments: list[Any], *, session_id: str) -> str:
"""Register only the images selected on THIS message, inside its own folder.
Client-provided paths are untrusted. No URL fetching, parent traversal or
symlink escape may turn an attachment into access to another private file.
"""
import mimetypes
from dodaios.agentic_ide.drops import dereference
from dodaios.core.image_references import MAX_BYTES, ImageReferenceError, get_store, instruction
refs = []
missing = []
root = Path(cwd).expanduser().resolve()
for index, item in enumerate(attachments, 1):
if item.kind != "image":
continue
try:
raw = dereference(item.reference)
path = (root / raw).resolve()
if not raw or not path.is_relative_to(root) or not path.is_file():
raise ImageReferenceError("Image is outside the chat folder or missing.")
if path.stat().st_size > MAX_BYTES:
raise ImageReferenceError("Image is too large for a handoff.")
mime = mimetypes.guess_type(path.name)[0] or ""
refs.append(get_store().add(
"chat:" + session_id, path.read_bytes(), mime, source=f"upload #{index}",
))
except (OSError, ValueError):
# No raw client paths in logs or error text; the ordinal identifies the chip.
missing.append(str(index))
note = instruction(refs)
if missing:
note += (
"\nVisual handoff unavailable for attachment(s) " + ", ".join(missing)
+ ". Do not send a task requiring those images or claim they were attached; "
"ask the user to attach them again."
)
return note
async def ingest(
cwd: str | Path,
*,
paths: list[str] | None = None,
uploads: Sequence[tuple[str, DropSource]] | None = None,
provider: str = "",
always_copy: bool = False,
) -> list[Any]:
"""Store what was dropped in ``cwd`` and read what is in it.
``paths`` are real locations the browser managed to hand over (an Explorer
or Finder drag usually carries them, and inside the desktop shell the host
resolves them for every drop). ``uploads`` are ``(name, bytes)`` for
everything with no path at all — a pasted screenshot, an image dragged off
a web page. An upload may also be an open binary file (the web server's
spooled copy), so a large one streams to disk instead of into memory.
A path already inside ``cwd`` is referenced where it lies; anything else is
copied in, because an agent's reach outside its working directory is
neither guaranteed nor silent.
Returns ``drop_analysis.DropAnalysis`` entries — one per file, in the order
they arrived. Raises :class:`AttachmentError` when nothing usable was
carried; an analysis that fails costs the description and nothing else, so
the file still travels.
"""
from dodaios.agentic_ide import drops
folder = Path(cwd).expanduser() # noqa: ASYNC240 — string work; the stat below is threaded
if not await asyncio.to_thread(folder.is_dir):
raise AttachmentError(f"Not a folder: {folder}")
references: list[str] = []
# (name, bytes, reference) for everything attached — the reference travels
# with the bytes so a description can never drift onto another file.
readable: list[tuple[str, bytes, str]] = []
to_copy: list[tuple[str, DropSource]] = []
for raw in paths or []:
candidate = (raw or "").strip()
if not candidate:
continue
inside = drops.within_workspace(candidate, folder)
if inside is not None and not always_copy:
reference = drops.reference(inside, agent=provider)
references.append(reference)
try:
body = await asyncio.to_thread(drops.read_for_analysis, folder / inside)
except OSError as exc:
# The reference still ships; the file simply goes undescribed.
log.info("chat attach: %r not readable for analysis (%s)", inside, exc)
else:
if body is not None:
readable.append((Path(inside).name, body, reference))
continue
# expanduser() is string work; the stat itself goes to a worker thread
# (a dropped file may live on a slow network share). The copy streams
# from the path, so a large recording is never held in memory.
resolved = Path(candidate).expanduser() # noqa: ASYNC240
if not await asyncio.to_thread(resolved.is_file):
log.info("chat attach: unreadable dropped path %r", candidate)
continue
to_copy.append((resolved.name, resolved))
for name, source in uploads or []:
to_copy.append((name or "file", source))
# ``store`` skips empty entries silently, so they are dropped HERE instead —
# that keeps ``stored[i]`` paired with ``to_copy[i]`` positionally.
sizes = await asyncio.to_thread(lambda: [drops.size_of(src) for _n, src in to_copy])
to_copy = [pair for pair, size in zip(to_copy, sizes, strict=True) if size != 0]
if to_copy:
try:
stored = await asyncio.to_thread(drops.store, folder, to_copy)
except drops.DropError as exc:
raise AttachmentError(str(exc)) from exc
for item, (_original, source) in zip(stored, to_copy, strict=True):
reference = drops.reference(item.relative_path, agent=provider)
references.append(reference)
# A file too large to analyse still ships; it goes undescribed.
body = await asyncio.to_thread(drops.read_for_analysis, source)
if body is not None:
readable.append((item.name, body, reference))
if not references:
raise AttachmentError("That attachment carried nothing this chat could use.")
return await _analyze(readable)
async def _analyze(readable: list[tuple[str, bytes, str]]) -> list[Any]:
"""Describe images and extract documents. Never raises — this is a bonus.
The files are already stored and referenced by the time this runs, so a
provider outage here must cost the description and nothing more.
"""
import mimetypes
from dodaios.agentic_ide import drop_analysis
from dodaios.brain.drop_context import DroppedItem
if not readable:
return []
items = [
(
DroppedItem(
name=name,
mime=mimetypes.guess_type(name)[0] or "application/octet-stream",
data=data,
),
reference,
)
for name, data, reference in readable
]
try:
return await drop_analysis.analyze(items)
except Exception as exc: # noqa: BLE001 — the attach itself already succeeded
log.info("chat attach: analysis failed (%s)", exc)
return []
def to_analysis(raw: list[dict[str, Any]] | None) -> list[Any]:
"""Rebuild the analyses a composer hands back on the wire.
The client holds what :func:`ingest` returned while the person finishes
typing, then posts it with the message. It is request data, so nothing here
may assume a shape: a malformed entry becomes an empty-detail attachment
rather than a 500 on a message somebody is waiting to send.
"""
from dodaios.agentic_ide import drop_analysis
out: list[Any] = []
for entry in raw or []:
if not isinstance(entry, dict):
continue
item = drop_analysis.DropAnalysis.from_dict(entry)
if item.name:
out.append(item)
return out
def compose(text: str, attachments: list[Any] | None) -> str:
"""The message as the turn will actually receive it.
The person's sentence first, then what was attached — the sentence is the
task, the files are context for it, and a model reads the instruction
better when it is not buried under a page of extracted PDF.
Returns ``text`` unchanged when nothing is attached, so an ordinary message
is never reshaped by a feature it did not use.
"""
from dodaios.agentic_ide.prompt_blueprint import attachment_block
said = (text or "").strip()
block = attachment_block(list(attachments or []))
if not block:
return said
lead = (
"Files the user attached to this message are below. Their contents are "
"given in full because the file itself may not be openable from here — "
"read them as part of the message."
)
return "\n\n".join(part for part in (said, lead, block) if part)