share_file

Make a file available to the user as a direct download link.

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

Parameters

Critical: path must be absolute

path must be an absolute filesystem path. A relative path like game_project.zip or workspace/report.csv will fail or resolve to the wrong location.

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