agent-framework-lib 0.8.8.post2__tar.gz → 0.8.8.post4__tar.gz

{agent_framework_lib-0.8.8.post2/agent_framework_lib.egg-info → agent_framework_lib-0.8.8.post4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-framework-lib
-Version: 0.8.8.post2
+Version: 0.8.8.post4
 Summary: A comprehensive Python framework for building and serving conversational AI agents with FastAPI
 Author-email: Sebastian Pavel <sebastian@cinco.ai>, Elliott Girard <elliott.girard@icloud.com>
 Maintainer-email: Sebastian Pavel <sebastian@cinco.ai>

{agent_framework_lib-0.8.8.post2 → agent_framework_lib-0.8.8.post4}/agent_framework/security/authz.py

@@ -55,6 +55,36 @@ def auth_required() -> bool:
     return not dev_mode_enabled()
 
 
+def trust_client_user_id() -> bool:
+    """Le déployeur fait confiance au client pour fournir le ``user_id``.
+
+    Activé via ``AUTH_TRUST_CLIENT_USER_ID``. Cas d'usage : un backend de
+    confiance authentifié par API key (un portail) qui multiplexe plusieurs
+    end-users et passe leur ``user_id`` en paramètre. Quand actif, le serveur
+    HONORE le ``user_id`` client (au lieu de le forcer au principal authentifié),
+    et ``is_owner`` autorise ce principal de confiance sur toute ressource —
+    l'auth (API key) reste exigée, mais le contrôle par end-user est délégué au
+    portail.
+
+    ⚠️ N'activer QUE si le client est de confiance et applique lui-même le
+    contrôle d'accès par end-user — sinon tout détenteur de la clé peut réclamer
+    n'importe quel ``user_id``.
+    """
+    return _env_flag("AUTH_TRUST_CLIENT_USER_ID")
+
+
+def resolve_effective_user_id(current_user: str, requested_user_id: str | None) -> str:
+    """Identité effective pour scoper sessions/fichiers.
+
+    Honore le ``user_id`` client quand l'auth est désactivée (dev mode) OU que le
+    déployeur fait confiance au client (``AUTH_TRUST_CLIENT_USER_ID``). Sinon, lie
+    au principal authentifié (anti-usurpation multi-tenant).
+    """
+    if requested_user_id and (not auth_required() or trust_client_user_id()):
+        return requested_user_id
+    return current_user
+
+
 def is_owner(resource_user_id: str | None, principal: str) -> bool:
     """Vérifie que ``principal`` possède la ressource.
 
@@ -64,14 +94,17 @@ def is_owner(resource_user_id: str | None, principal: str) -> bool:
         principal: Identité authentifiée demandant l'accès.
 
     Returns:
-        ``True`` si le principal possède la ressource, ou si le mode
-        développement est actif et que le principal est ``"anonymous"``
-        (compat mono-utilisateur).
+        ``True`` si le principal possède la ressource, si le mode développement
+        est actif et que le principal est ``"anonymous"`` (compat mono-utilisateur),
+        ou si le client est de confiance (``AUTH_TRUST_CLIENT_USER_ID`` — le portail
+        de confiance peut accéder aux ressources de n'importe quel end-user).
     """
     if resource_user_id is not None and resource_user_id == principal:
         return True
     if dev_mode_enabled() and principal == ANONYMOUS_PRINCIPAL:
         return True
+    if trust_client_user_id():
+        return True
     return False
 
 

{agent_framework_lib-0.8.8.post2 → agent_framework_lib-0.8.8.post4}/agent_framework/security/sandbox_provider.py

@@ -474,12 +474,23 @@ class OpenShellProvider(SandboxProvider):
         src = f"{SANDBOX_OUTPUT}/{_safe_name(out_subdir)}" if out_subdir else SANDBOX_OUTPUT
         # Source dir may not exist if the command wrote nothing — tolerate failure.
         proc = self._run_cli(["sandbox", "download", name, src, dest_dir], timeout=120)
+        # Visibility: this PULL is the only file-delivery path in the sandboxed
+        # topology, so its outcome must be observable (was DEBUG → silent file loss).
+        try:
+            pulled = sum(len(files) for _, _, files in os.walk(dest_dir))
+        except OSError:
+            pulled = -1
         if proc.returncode != 0:
-            logger.debug(
-                "openshell download (no output?) for %s: %s",
+            logger.warning(
+                "[sandbox] download failed for %s (src=%s) rc=%s — generated files "
+                "may be lost: %s",
                 name,
-                (proc.stdout + proc.stderr).strip()[:200],
+                src,
+                proc.returncode,
+                (proc.stdout + proc.stderr).strip()[:300],
             )
+        else:
+            logger.info("[sandbox] pulled %d file(s) from %s for %s", pulled, src, name)
         # Best-effort: remove the per-command subdir so a long-lived session does
         # not accumulate output slices in /sandbox/output.
         if out_subdir:

{agent_framework_lib-0.8.8.post2 → agent_framework_lib-0.8.8.post4}/agent_framework/skills/builtin/scripts/create_and_register.py

@@ -164,12 +164,16 @@ def main() -> None:
 
     skill, filename, output_dir, extra_args = _parse_args(sys.argv[1:])
 
-    # Default to the per-invocation AGENT_OUTPUT_DIR when no explicit directory
-    # is given. This guarantees that generated files land where the ShellTool
-    # passive finalizer scans, so they are registered (and their links surfaced)
-    # even if this process is killed before it can upload them itself.
-    if not output_dir:
-        output_dir = os.environ.get("AGENT_OUTPUT_DIR") or None
+    # Always write the generated file INTO AGENT_OUTPUT_DIR when it is set (the
+    # per-command directory the ShellTool parent finalizer collects). We strip any
+    # directory from --filename and override a caller-supplied --output-dir so a
+    # generated file can NEVER land somewhere the finalizer does not look (e.g.
+    # /tmp). Outside a finalizer context (AGENT_OUTPUT_DIR unset) the caller's
+    # --output-dir is honored as before.
+    agent_output_dir = os.environ.get("AGENT_OUTPUT_DIR")
+    if agent_output_dir:
+        output_dir = agent_output_dir
+    filename = os.path.basename(filename)
 
     module = SKILL_MODULE_MAP.get(skill)
     if module is None:
@@ -179,23 +183,26 @@ def main() -> None:
 
     _verify_file(filepath)
 
-    # In the per-session sandbox the network is cut: the in-shell HTTP upload
-    # cannot reach the server. The file is left in AGENT_OUTPUT_DIR and the
-    # ShellTool parent finalizer (which HAS network + creds) registers it. We
-    # must NOT print a file_id here, otherwise the finalizer treats the file as
-    # already uploaded and skips it → the link 404s.
-    skip_upload = os.environ.get("AGENT_SKILL_SKIP_HTTP_UPLOAD", "").lower() in ("1", "true", "yes")
-    upload_result = {} if skip_upload else _upload_file(filepath)
-
-    # Local file is kept by default so downstream consumers (e.g. PowerPoint skill
-    # embedding charts/mermaid) can still read it. Set AGENT_CLEANUP_LOCAL=1 in the
-    # environment to delete it after successful upload.
+    # Delivery is the ShellTool parent finalizer's job (it has network + creds; the
+    # sandbox does not). The in-shell HTTP upload is OFF by default and never runs
+    # in the sandbox: it derails the agent (401 on an unreachable target) and a
+    # printed file_id makes the finalizer skip the file. Opt in explicitly with
+    # AGENT_SKILL_HTTP_UPLOAD=1 for legacy/local non-finalizer flows only.
+    do_upload = os.environ.get("AGENT_SKILL_HTTP_UPLOAD", "").lower() in ("1", "true", "yes")
+    upload_result = _upload_file(filepath) if do_upload else {}
+
+    # Keep the local file unless an explicit upload happened AND cleanup is asked:
+    # the finalizer needs the file on disk to deliver it. Never delete on the
+    # default (no-upload) path, or there would be nothing left to register.
     local_cleaned = False
-    if os.environ.get("AGENT_CLEANUP_LOCAL", "").lower() in ("1", "true", "yes"):
+    if (
+        do_upload
+        and upload_result
+        and os.environ.get("AGENT_CLEANUP_LOCAL", "").lower() in ("1", "true", "yes")
+    ):
         local_cleaned = _cleanup(filepath)
 
     mime = _guess_mime(filepath)
-    size_bytes = upload_result.get("size_bytes", 0)
 
     output = {
         "status": "success",
@@ -203,13 +210,24 @@ def main() -> None:
         # table, image_gen) so callers can embed the local PNG when needed.
         # Empty if local was cleaned up.
         "file": "" if local_cleaned else filepath,
-        "file_id": upload_result.get("file_id", ""),
-        "download_url": upload_result.get("download_url", ""),
         "filename": os.path.basename(filepath),
-        "size_bytes": size_bytes,
         "mime_type": mime,
         "local_cleaned": local_cleaned,
+        # The file is created; the framework delivers it to storage automatically
+        # and appends the download link to this command's result. The agent must
+        # NOT try to upload or authenticate.
+        "delivery": "automatic",
+        "message": (
+            f"File '{os.path.basename(filepath)}' created successfully and is being "
+            "delivered to storage automatically — the download link appears in this "
+            "command's result. Do not upload or authenticate."
+        ),
     }
+    # Surface storage fields ONLY when an explicit upload actually happened.
+    if upload_result:
+        output["file_id"] = upload_result.get("file_id", "")
+        output["download_url"] = upload_result.get("download_url", "")
+        output["size_bytes"] = upload_result.get("size_bytes", 0)
     print(json.dumps(output))
 
 

{agent_framework_lib-0.8.8.post2 → agent_framework_lib-0.8.8.post4}/agent_framework/skills/builtin/skills/chart/SKILL.md

@@ -224,13 +224,17 @@ echo '{
 
 ### Output Format (stdout)
 
-On success, the script prints a JSON object to stdout with the download URL:
+On success, the script prints a JSON object confirming the file was created:
 
 ```json
-{"status": "success", "file_id": "uuid", "download_url": "/files/uuid/download", "filename": "monthly_sales.png", "size_bytes": 1234, "mime_type": "image/png", "local_cleaned": true}
+{"status": "success", "filename": "monthly_sales.png", "mime_type": "image/png", "delivery": "automatic", "message": "File 'monthly_sales.png' created successfully and is being delivered to storage automatically — the download link appears in this command's result."}
 ```
 
-Use the `download_url` to provide the user with a download link: `[monthly_sales.png](/files/uuid/download)`
+The file is delivered to storage **automatically** by the framework — you do NOT
+upload, register, or authenticate anything. The download link
+(`/files/<uuid>/download`) is appended to this command's result; present it to the
+user as `[monthly_sales.png](/files/<uuid>/download)`. Do not improvise an upload or
+write the file elsewhere — just run the command above and read the link from the result.
 
 ### ⚠️ Generating MULTIPLE images — read this carefully
 

{agent_framework_lib-0.8.8.post2 → agent_framework_lib-0.8.8.post4}/agent_framework/skills/builtin/skills/csv/SKILL.md

@@ -92,14 +92,15 @@ Widget C,39.99,200
 
 ### Output Format (stdout)
 
+On success, the script prints a JSON object confirming the file was created:
+
 ```json
 {
   "status": "success",
-  "file_id": "uuid",
-  "download_url": "/files/uuid/download",
   "filename": "products.csv",
-  "size_bytes": 124,
   "mime_type": "text/csv",
+  "delivery": "automatic",
+  "message": "File 'products.csv' created successfully and is being delivered to storage automatically — the download link appears in this command's result.",
   "metadata": {
     "rows": 3,
     "columns": 3,
@@ -108,6 +109,12 @@ Widget C,39.99,200
 }
 ```
 
+The file is delivered to storage **automatically** by the framework — you do NOT
+upload, register, or authenticate anything. The download link
+(`/files/<uuid>/download`) is appended to this command's result; present it to the
+user as `[products.csv](/files/<uuid>/download)`. Do not improvise an upload or write
+the file elsewhere — just run the command above and read the link from the result.
+
 ---
 
 ## Operation 2: Read CSV to JSON
@@ -276,12 +283,15 @@ uv run python agent_framework/skills/builtin/skills/csv/transform_csv.py \
 
 ### Output Format (stdout)
 
+On success, the script prints a JSON object confirming the file was created:
+
 ```json
 {
   "status": "success",
-  "file_id": "uuid",
-  "download_url": "/files/uuid/download",
   "filename": "filtered.csv",
+  "mime_type": "text/csv",
+  "delivery": "automatic",
+  "message": "File 'filtered.csv' created successfully and is being delivered to storage automatically — the download link appears in this command's result.",
   "metadata": {
     "input_rows": 100,
     "output_rows": 25,
@@ -290,6 +300,12 @@ uv run python agent_framework/skills/builtin/skills/csv/transform_csv.py \
 }
 ```
 
+The file is delivered to storage **automatically** by the framework — you do NOT
+upload, register, or authenticate anything. The download link
+(`/files/<uuid>/download`) is appended to this command's result; present it to the
+user as `[filtered.csv](/files/<uuid>/download)`. Do not improvise an upload or write
+the file elsewhere — just run the command above and read the link from the result.
+
 ---
 
 ## Error Handling (stderr)

{agent_framework_lib-0.8.8.post2 → agent_framework_lib-0.8.8.post4}/agent_framework/skills/builtin/skills/drawio/SKILL.md

@@ -79,13 +79,17 @@ uv run python -m agent_framework.skills.builtin.scripts.create_and_register --sk
 
 ### Output Format (stdout)
 
-On success, the script prints a JSON object to stdout with the download URL:
+On success, the script prints a JSON object confirming the file was created:
 
 ```json
-{"status": "success", "file_id": "uuid", "download_url": "/files/uuid/download", "filename": "order_flow.drawio", "size_bytes": 1234, "mime_type": "application/xml", "local_cleaned": true}
+{"status": "success", "filename": "order_flow.drawio", "mime_type": "application/xml", "delivery": "automatic", "message": "File 'order_flow.drawio' created successfully and is being delivered to storage automatically — the download link appears in this command's result."}
 ```
 
-Use the `download_url` to provide the user with a download link: `[order_flow.drawio](/files/uuid/download)`
+The file is delivered to storage **automatically** by the framework — you do NOT
+upload, register, or authenticate anything. The download link
+(`/files/<uuid>/download`) is appended to this command's result; present it to the
+user as `[order_flow.drawio](/files/<uuid>/download)`. Do not improvise an upload or
+write the file elsewhere — just run the command above and read the link from the result.
 
 ### Error Handling (stderr)
 

{agent_framework_lib-0.8.8.post2 → agent_framework_lib-0.8.8.post4}/agent_framework/skills/builtin/skills/excel/SKILL.md

@@ -74,17 +74,17 @@ echo '[
 
 ### Output Format (stdout)
 
-On success, the script prints a JSON object to stdout with the download URL:
+On success, the script prints a JSON object confirming the file was created:
 
 ```json
-{"status": "success", "file_id": "uuid", "download_url": "/files/uuid/download", "filename": "sales_report.xlsx", "size_bytes": 1234, "mime_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "local_cleaned": true}
+{"status": "success", "filename": "sales_report.xlsx", "mime_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "delivery": "automatic", "message": "File 'sales_report.xlsx' created successfully and is being delivered to storage automatically — the download link appears in this command's result."}
 ```
 
-Use the `download_url` from this response to provide the user with a download link:
-
-```
-[sales_report.xlsx](/files/uuid/download)
-```
+The file is delivered to storage **automatically** by the framework — you do NOT
+upload, register, or authenticate anything. The download link
+(`/files/<uuid>/download`) is appended to this command's result; present it to the
+user as `[sales_report.xlsx](/files/<uuid>/download)`. Do not improvise an upload or
+write the file elsewhere — just run the command above and read the link from the result.
 
 ### Error Handling (stderr)
 

{agent_framework_lib-0.8.8.post2 → agent_framework_lib-0.8.8.post4}/agent_framework/skills/builtin/skills/file/SKILL.md

@@ -76,11 +76,17 @@ echo "Hello, world!" | uv run python -m agent_framework.skills.builtin.scripts.c
 
 #### Output Format (stdout)
 
+On success, the script prints a JSON object confirming the file was created:
+
 ```json
-{"status": "success", "file_id": "uuid", "download_url": "/files/uuid/download", "filename": "report.txt", "size_bytes": 1234, "mime_type": "text/plain", "local_cleaned": true}
+{"status": "success", "filename": "report.txt", "mime_type": "text/plain", "delivery": "automatic", "message": "File 'report.txt' created successfully and is being delivered to storage automatically — the download link appears in this command's result."}
 ```
 
-Use the `download_url` to provide the user with a download link: `[report.txt](/files/uuid/download)`
+The file is delivered to storage **automatically** by the framework — you do NOT
+upload, register, or authenticate anything. The download link
+(`/files/<uuid>/download`) is appended to this command's result; present it to the
+user as `[report.txt](/files/<uuid>/download)`. Do not improvise an upload or write
+the file elsewhere — just run the command above and read the link from the result.
 
 #### Error Handling (stderr)
 

{agent_framework_lib-0.8.8.post2 → agent_framework_lib-0.8.8.post4}/agent_framework/skills/builtin/skills/image_gen/SKILL.md

@@ -192,17 +192,15 @@ To use DALL-E 3 instead, set `"model": "dall-e-3"` (with `quality` `standard`/`h
 
 ## Output Format (stdout)
 
-On success, the script prints a JSON object with download information:
+On success, the script prints a JSON object confirming the file was created:
 
 ```json
 {
   "status": "success",
-  "file_id": "uuid",
-  "download_url": "/files/uuid/download",
   "filename": "mountain_landscape.png",
-  "size_bytes": 234567,
   "mime_type": "image/png",
-  "local_cleaned": true,
+  "delivery": "automatic",
+  "message": "File 'mountain_landscape.png' created successfully and is being delivered to storage automatically — the download link appears in this command's result.",
   "metadata": {
     "model": "gpt-image-1",
     "size": "1536x1024",
@@ -214,10 +212,11 @@ On success, the script prints a JSON object with download information:
 
 **Note**: The `revised_prompt` field (when provided by the model) shows how OpenAI interpreted and enhanced your original prompt.
 
-Use the `download_url` to provide a download link:
-```
-[Download image](/files/uuid/download)
-```
+The file is delivered to storage **automatically** by the framework — you do NOT
+upload, register, or authenticate anything. The download link
+(`/files/<uuid>/download`) is appended to this command's result; present it to the
+user as `[mountain_landscape.png](/files/<uuid>/download)`. Do not improvise an upload or
+write the file elsewhere — just run the command above and read the link from the result.
 
 ---
 

{agent_framework_lib-0.8.8.post2 → agent_framework_lib-0.8.8.post4}/agent_framework/skills/builtin/skills/mermaid/SKILL.md

@@ -145,13 +145,17 @@ echo 'sequenceDiagram
 
 ### Output Format (stdout)
 
-On success, the script prints a JSON object to stdout with the download URL:
+On success, the script prints a JSON object confirming the file was created:
 
 ```json
-{"status": "success", "file_id": "uuid", "download_url": "/files/uuid/download", "filename": "diagram.png", "size_bytes": 1234, "mime_type": "image/png", "local_cleaned": true}
+{"status": "success", "filename": "diagram.png", "mime_type": "image/png", "delivery": "automatic", "message": "File 'diagram.png' created successfully and is being delivered to storage automatically — the download link appears in this command's result."}
 ```
 
-Use the `download_url` to provide the user with a download link: `[diagram.png](/files/uuid/download)`
+The file is delivered to storage **automatically** by the framework — you do NOT
+upload, register, or authenticate anything. The download link
+(`/files/<uuid>/download`) is appended to this command's result; present it to the
+user as `[diagram.png](/files/<uuid>/download)`. Do not improvise an upload or write
+the file elsewhere — just run the command above and read the link from the result.
 
 ### Error Handling (stderr)
 

{agent_framework_lib-0.8.8.post2 → agent_framework_lib-0.8.8.post4}/agent_framework/skills/builtin/skills/powerpoint/SKILL.md

@@ -770,17 +770,15 @@ echo '{
 
 ## Output Format (stdout)
 
-On success, the script prints a JSON object with download information:
+On success, the script prints a JSON object confirming the file was created:
 
 ```json
 {
   "status": "success",
-  "file_id": "uuid",
-  "download_url": "/files/uuid/download",
   "filename": "Q4_review.pptx",
-  "size_bytes": 45678,
   "mime_type": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
-  "local_cleaned": true,
+  "delivery": "automatic",
+  "message": "File 'Q4_review.pptx' created successfully and is being delivered to storage automatically — the download link appears in this command's result.",
   "metadata": {
     "slide_count": 12,
     "theme": "consulting",
@@ -805,10 +803,11 @@ On success, the script prints a JSON object with download information:
 | `assets_generated` | int | Number of assets generated via external skills |
 | `suggested_structure` | array or null | Slide structure plan (deck strategy mode only) |
 
-Use the `download_url` to provide a download link:
-```
-[Download presentation](/files/uuid/download)
-```
+The file is delivered to storage **automatically** by the framework — you do NOT
+upload, register, or authenticate anything. The download link
+(`/files/<uuid>/download`) is appended to this command's result; present it to the
+user as `[Q4_review.pptx](/files/<uuid>/download)`. Do not improvise an upload or write
+the file elsewhere — just run the command above and read the link from the result.
 
 ---
 

{agent_framework_lib-0.8.8.post2 → agent_framework_lib-0.8.8.post4}/agent_framework/skills/builtin/skills/table/SKILL.md

@@ -156,13 +156,17 @@ echo '{
 
 ### Output Format (stdout)
 
-On success, the script prints a JSON object to stdout with the download URL:
+On success, the script prints a JSON object confirming the file was created:
 
 ```json
-{"status": "success", "file_id": "uuid", "download_url": "/files/uuid/download", "filename": "sales_table.png", "size_bytes": 1234, "mime_type": "image/png", "local_cleaned": true}
+{"status": "success", "filename": "sales_table.png", "mime_type": "image/png", "delivery": "automatic", "message": "File 'sales_table.png' created successfully and is being delivered to storage automatically — the download link appears in this command's result."}
 ```
 
-Use the `download_url` to provide the user with a download link: `[sales_table.png](/files/uuid/download)`
+The file is delivered to storage **automatically** by the framework — you do NOT
+upload, register, or authenticate anything. The download link
+(`/files/<uuid>/download`) is appended to this command's result; present it to the
+user as `[sales_table.png](/files/<uuid>/download)`. Do not improvise an upload or write
+the file elsewhere — just run the command above and read the link from the result.
 
 ### Error Handling (stderr)
 

{agent_framework_lib-0.8.8.post2 → agent_framework_lib-0.8.8.post4}/agent_framework/skills/builtin/skills/unified_pdf/SKILL.md

@@ -156,13 +156,17 @@ echo '<h1>Meeting Notes</h1>
 
 ### Output Format (stdout)
 
-On success, the script prints a JSON object to stdout with the download URL:
+On success, the script prints a JSON object confirming the file was created:
 
 ```json
-{"status": "success", "file_id": "uuid", "download_url": "/files/uuid/download", "filename": "report.pdf", "size_bytes": 1234, "mime_type": "application/pdf", "local_cleaned": true}
+{"status": "success", "filename": "report.pdf", "mime_type": "application/pdf", "delivery": "automatic", "message": "File 'report.pdf' created successfully and is being delivered to storage automatically — the download link appears in this command's result."}
 ```
 
-Use the `download_url` to provide the user with a download link: `[report.pdf](/files/uuid/download)`
+The file is delivered to storage **automatically** by the framework — you do NOT
+upload, register, or authenticate anything. The download link
+(`/files/<uuid>/download`) is appended to this command's result; present it to the
+user as `[report.pdf](/files/<uuid>/download)`. Do not improvise an upload or write
+the file elsewhere — just run the command above and read the link from the result.
 
 ### Error Handling (stderr)
 

{agent_framework_lib-0.8.8.post2 → agent_framework_lib-0.8.8.post4}/agent_framework/skills/builtin/skills/word/SKILL.md

@@ -335,28 +335,17 @@ echo '{
 
 ## Output Format (stdout)
 
-On success, the script prints a JSON object with download information:
+On success, the script prints a JSON object confirming the file was created:
 
 ```json
-{
-  "status": "success",
-  "file_id": "uuid",
-  "download_url": "/files/uuid/download",
-  "filename": "Q4_2024_Report.docx",
-  "size_bytes": 78456,
-  "mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
-  "local_cleaned": true,
-  "metadata": {
-    "section_count": 10,
-    "page_count": 3
-  }
-}
+{"status": "success", "filename": "Q4_2024_Report.docx", "mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "delivery": "automatic", "message": "File 'Q4_2024_Report.docx' created successfully and is being delivered to storage automatically — the download link appears in this command's result."}
 ```
 
-Use the `download_url` to provide a download link:
-```
-[Download document](/files/uuid/download)
-```
+The file is delivered to storage **automatically** by the framework — you do NOT
+upload, register, or authenticate anything. The download link
+(`/files/<uuid>/download`) is appended to this command's result; present it to the
+user as `[Q4_2024_Report.docx](/files/<uuid>/download)`. Do not improvise an upload or
+write the file elsewhere — just run the command above and read the link from the result.
 
 ---
 

{agent_framework_lib-0.8.8.post2 → agent_framework_lib-0.8.8.post4}/agent_framework/tools/shell_tool.py

@@ -175,6 +175,10 @@ class ShellTool(AgentTool):
         # Avoids rescanning os.environ + rebuilding the redactor on every command.
         self._redactor: SecretRedactor | None = None
         self._redactor_env_values: list[str] | None = None
+        # Per-command ephemeral secrets (e.g. the minted AGENT_SESSION_TOKEN). These
+        # never live in os.environ, so the env-scan redactor would miss them — they
+        # are registered here at mint time so they are masked in shell output.
+        self._ephemeral_secret_values: set[str] = set()
 
     def set_skill_env_provider(self, provider: Callable[[], Iterable[str]] | None) -> None:
         """Set the callback that lists env vars required by loaded skills.
@@ -250,7 +254,11 @@ class ShellTool(AgentTool):
 
         if self._redactor_env_values is None:
             self._redactor_env_values = sensitive_env_values(os.environ)
-        values = [*self._redactor_env_values, *self._workspace_secrets.values()]
+        values = [
+            *self._redactor_env_values,
+            *self._workspace_secrets.values(),
+            *self._ephemeral_secret_values,
+        ]
         self._redactor = SecretRedactor(values)
         return self._redactor
 
@@ -347,9 +355,15 @@ class ShellTool(AgentTool):
                 from agent_framework.security.upload_token import sign_upload_token
 
                 ttl = _env_int("SHELL_SESSION_TOKEN_TTL", 1800)
-                env["AGENT_SESSION_TOKEN"] = sign_upload_token(
+                token = sign_upload_token(
                     self.current_user_id, self.current_session_id, ttl=ttl
                 )
+                env["AGENT_SESSION_TOKEN"] = token
+                # Register the ephemeral token so it is masked in shell output
+                # (it is never in os.environ → the env-scan redactor would miss it,
+                # e.g. a leak via `env` in the shell). Invalidate the cached redactor.
+                self._ephemeral_secret_values.add(token)
+                self._redactor = None
             except Exception as e:  # noqa: BLE001 — never let token minting break the shell
                 logger.warning("ShellTool: session token minting failed: %s", e)
         # Ensure server connection info is available
@@ -763,9 +777,15 @@ class ShellTool(AgentTool):
                 from agent_framework.security.upload_token import sign_upload_token
 
                 ttl = _env_int("SHELL_SESSION_TOKEN_TTL", 1800)
-                env["AGENT_SESSION_TOKEN"] = sign_upload_token(
+                token = sign_upload_token(
                     self.current_user_id, self.current_session_id, ttl=ttl
                 )
+                env["AGENT_SESSION_TOKEN"] = token
+                # Register the ephemeral token so it is masked in shell output
+                # (it is never in os.environ → the env-scan redactor would miss it,
+                # e.g. a leak via `env` in the shell). Invalidate the cached redactor.
+                self._ephemeral_secret_values.add(token)
+                self._redactor = None
             except Exception as e:  # noqa: BLE001 — never let token minting break the shell
                 logger.warning("ShellTool: sandbox session token minting failed: %s", e)
 
@@ -846,8 +866,20 @@ class ShellTool(AgentTool):
                 )
                 return out
 
-            with contextlib.suppress(Exception):
+            # Pull the files the sandbox produced out via the gateway. This is the
+            # ONLY delivery path in the sandboxed topology (the sandbox itself has
+            # no route to register them). Failures here = lost files, so they MUST
+            # be visible (previously swallowed silently → undiagnosable file loss).
+            try:
                 provider.collect_out(session_id, collect_dir, out_subdir=out_subdir)
+            except Exception as e:  # noqa: BLE001 — never raise into the agent
+                logger.warning(
+                    "[ShellTool] collect_out failed (session=%s, out_subdir=%s) — "
+                    "generated files may not be delivered: %s",
+                    session_id,
+                    out_subdir,
+                    e,
+                )
 
             stdout = result.stdout or ""
             stderr = result.stderr or ""