share_file

Copy an existing local file into the current session directory and return a direct download link.

share_file and content_publish are different tools:

• share_file = copy a local file into session_files/{session_id}/ + return a download link.
• content_publish = register a file that is already in session_files/{session_id}/ + show it as an inline viewer/card.

Use share_file when the user should keep/download the file. Use content_publish when the user should inspect it directly in chat.

When to call

Call this any time you produce a file the user will want to keep:

• Archives (.zip, .tar.gz)
• Generated documents (.pdf, .docx, .csv, .json)
• Built binaries or packages
• Any output file created by terminal, code_exec, or filesystem

Do not use this just to create an inline preview. For SVG/HTML/PDF/image/video/STL preview cards, put the file in the session directory and call content_publish.

How it works

1. Takes an absolute source path.
2. Copies that file into the current session directory: session_files/{session_id}/ by default.
3. If the target filename already exists, creates a numbered filename instead of overwriting.
4. Returns a URL: /sessions/{session_id}/files/{filename}.
5. The original source file remains unchanged.

Maximum file size: SHARE_FILE_MAX_SIZE_MB, default 1024 MB (1 GB).

Parameters

Critical: path must be absolute

path must be an absolute filesystem path. A relative path like game_project.zip or workspace/report.csv is rejected.

How to get the absolute path

Option 1 — you just wrote the file with filesystem or terminal, you know the full path:

path: "/home/gmikcon/Projects/navi-1/workspace/game_project.zip"

Option 2 — you only have a relative path, resolve it first:

terminal(command="realpath game_project.zip")
# → /home/gmikcon/Projects/navi-1/game_project.zip

Option 3 — use filesystem(action="info", path="workspace/game_project.zip") — the result includes the absolute path.

What to do with the result

On success the tool returns:

Download ready: game_project.zip (4.2 MB)
URL: http://server:8000/sessions/abc123/files/game_project.zip

You must include the URL in your reply to the user. Format it as a markdown link:

Here's your file: [game_project.zip](http://server:8000/sessions/abc123/files/game_project.zip)

Do not just say "the file is ready" without the link. The user cannot find the URL themselves.

Full example

# 1. Create the archive
terminal(command="cd /home/gmikcon/Projects && zip -r /tmp/game_project.zip game_project/")

# 2. Share it — use the absolute path from step 1
share_file(path="/tmp/game_project.zip", filename="game_project.zip")

# 3. In your reply:
"Here's the archive: [game_project.zip](http://...)"

Common mistakes