auto-coder 3.0.44__tar.gz → 3.0.46__tar.gz

{auto_coder-3.0.44/src/auto_coder.egg-info → auto_coder-3.0.46}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: auto-coder
-Version: 3.0.44
+Version: 3.0.46
 Summary: AutoCoder: AutoCoder
 Author: allwefantasy
 Author-email: allwefantasy <allwefantasy@gmail.com>
@@ -247,6 +247,7 @@ Auto-Coder (powered by Byzer-LLM)
 ---
 
 *Latest News* 🔥
+- [2026/04-demo] Auto-Coder 教程视频录制演示
 - [2025/01] Release Auto-Coder 0.1.208
 - [2024/09] Release Auto-Coder 0.1.163
 - [2024/08] Release Auto-Coder 0.1.143

{auto_coder-3.0.44 → auto_coder-3.0.46}/README.md

@@ -16,6 +16,7 @@ Auto-Coder (powered by Byzer-LLM)
 ---
 
 *Latest News* 🔥
+- [2026/04-demo] Auto-Coder 教程视频录制演示
 - [2025/01] Release Auto-Coder 0.1.208
 - [2024/09] Release Auto-Coder 0.1.163
 - [2024/08] Release Auto-Coder 0.1.143

{auto_coder-3.0.44 → auto_coder-3.0.46}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "auto-coder"
-version = "3.0.44"
+version = "3.0.46"
 description = "AutoCoder: AutoCoder"
 authors = [
     {name = "allwefantasy", email = "allwefantasy@gmail.com"}

{auto_coder-3.0.44 → auto_coder-3.0.46/src/auto_coder.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: auto-coder
-Version: 3.0.44
+Version: 3.0.46
 Summary: AutoCoder: AutoCoder
 Author: allwefantasy
 Author-email: allwefantasy <allwefantasy@gmail.com>
@@ -247,6 +247,7 @@ Auto-Coder (powered by Byzer-LLM)
 ---
 
 *Latest News* 🔥
+- [2026/04-demo] Auto-Coder 教程视频录制演示
 - [2025/01] Release Auto-Coder 0.1.208
 - [2024/09] Release Auto-Coder 0.1.163
 - [2024/08] Release Auto-Coder 0.1.143

{auto_coder-3.0.44 → auto_coder-3.0.46}/src/auto_coder.egg-info/SOURCES.txt

@@ -805,9 +805,11 @@ src/autocoder/terminal/utils/errors.py
 src/autocoder/terminal/utils/paths.py
 src/autocoder/terminal/utils/shell.py
 src/autocoder/terminal_core/__init__.py
+src/autocoder/terminal_core/cloud_block_command.py
 src/autocoder/terminal_core/cloud_bridge.py
 src/autocoder/terminal_core/cloud_command_dispatcher.py
 src/autocoder/terminal_core/cloud_config.py
+src/autocoder/terminal_core/cloud_file_uploader.py
 src/autocoder/terminal_core/command_registry.py
 src/autocoder/terminal_core/execution_broker.py
 src/autocoder/terminal_core/forward_input.py

{auto_coder-3.0.44 → auto_coder-3.0.46}/src/autocoder/common/llms/registry.py

@@ -250,6 +250,20 @@ DEFAULT_MODELS = [
         "max_output_tokens": 128000,
         "context_window": 1000000,
     },
+    {
+        "name": "openrouter/claude-opus-4-7",
+        "description": "Claude Opus 4.7 via OpenRouter，Anthropic 最强编程模型，适合长流程 Agent 任务",
+        "model_name": "anthropic/claude-opus-4.7",
+        "model_type": "saas/openai",
+        "base_url": "https://openrouter.ai/api/v1",
+        "provider": "openrouter",
+        "api_key_path": "",
+        "is_reasoning": True,
+        "input_price": 36.0,  # $5/百万tokens ≈ 36元
+        "output_price": 180.0,  # $25/百万tokens ≈ 180元
+        "max_output_tokens": 128000,
+        "context_window": 1000000,
+    },
     {
         "name": "openrouter/openai/gpt-5",
         "description": "GPT-5 via OpenRouter，OpenAI 最新模型",

{auto_coder-3.0.44 → auto_coder-3.0.46}/src/autocoder/common/shells.py

@@ -25,11 +25,15 @@ from autocoder.common.result_manager import ResultManager
 # 染绿/红,灰色小字显示 ``exit``。命令体输出保持原样(可能已含 ANSI 色),避免
 # 二次解析破坏。
 #
-# 读取 ``enable_rich_render`` 配置(默认 True),用户可 ``/conf enable_rich_render:false``
-# 关闭;环境变量 ``AUTOCODER_V3_MARKDOWN=0`` 也会关闭(与 markdown 渲染共用开关,
-# 因为它们本质都是"rich 美化"的一部分)。
+# 是否启用 Rich 美化由"消费端是否是 TTY/能渲染 ANSI"决定,通过 ``pretty`` 参数
+# 由调用方显式指定:
+#   - TUI / 交互式 CLI → pretty=True(默认),产出 ANSI 色码
+#   - CloudBridge / Web / 日志文件 → pretty=False,只产出纯文本
+# 另外保留 ``enable_rich_render`` 配置与 ``AUTOCODER_V3_MARKDOWN`` 环境变量作为
+# TUI 侧的用户级总开关(pretty=True 时才生效);pretty=False 一律按纯文本处理,
+# 不受全局配置影响,这样 CloudBridge 链路是确定的。
 def _is_rich_compact_header_enabled() -> bool:
-    """shells.py 本身被 SDK/CLI 等多处复用,因此配置读取必须软失败。
+    """判断 TUI 侧用户是否把 Rich 关掉了。仅在 ``pretty=True`` 时才查询。
 
     - 环境变量优先,便于在不动配置的前提下排查问题
     - memory_manager 没初始化/读失败,一律按 True 处理
@@ -59,13 +63,27 @@ def _is_rich_compact_header_enabled() -> bool:
     return True
 
 
-def _print_compact_shell_header(user_command: str, return_code: int) -> None:
+def _print_compact_shell_header(
+    user_command: str, return_code: int, pretty: bool = True
+) -> None:
     """输出 ``$ <cmd>   exit <N>`` 形式的命令头。
 
-    - rich 启用时:``$`` 深灰、命令名亮蓝加粗、``exit 0`` 绿色/非零红色
-    - 关闭时:退回最早的 ``\\033[90m`` 手写 ANSI,保持向后兼容
+    Args:
+        user_command: 用户输入的原始命令
+        return_code: 进程退出码
+        pretty: 消费端是否是 TTY / 能渲染 ANSI。
+            - True(默认):TUI/交互式 CLI 场景,产出 Rich 彩色头
+              (用户配置关闭时退回朴素灰色 ANSI)
+            - False:CloudBridge/Web 等非 TTY 场景,产出纯文本,
+              形如 ``$ <cmd>   exit <N>``,不含任何转义序列
     """
+    if not pretty:
+        # 非 TTY 消费端:确定性纯文本,不读任何配置、不出任何 ANSI
+        print(f"$ {user_command}   exit {return_code}")
+        return
+
     if not _is_rich_compact_header_enabled():
+        # TTY 消费端但用户关了 Rich:退回手写 ANSI(保持向后兼容)
         print(f"$ {user_command}\033[90m  exit {return_code}\033[0m")
         return
 
@@ -99,6 +117,22 @@ def _print_compact_shell_header(user_command: str, return_code: int) -> None:
         print(f"$ {user_command}\033[90m  exit {return_code}\033[0m")
 
 
+# pretty=False 时注入给子进程的禁色环境变量。
+# 绝大多数带 TTY 自检的 CLI(cursor-agent、git、pip、npm、cargo、uv、ripgrep、
+# bat、ls、jq 等)都至少识别其中一个,从而在启动时就不产出 ANSI 色码,这样上游
+# 无需再做 strip,性能和保真度都更好。
+_NO_COLOR_ENV: dict[str, str] = {
+    "NO_COLOR": "1",          # https://no-color.org/ 业界事实标准
+    "TERM": "dumb",           # 让 readline / curses / rich 判定为非终端
+    "FORCE_COLOR": "0",       # Node 生态(npm/pnpm/yarn/chalk)
+    "CLICOLOR": "0",          # BSD ls / macOS ls
+    "CLICOLOR_FORCE": "0",
+    "PY_COLORS": "0",         # pytest / rich 兜底
+    "ANSI_COLORS_DISABLED": "1",
+    "COLORTERM": "",          # 清空防止覆盖 TERM=dumb 判断
+}
+
+
 def get_terminal_name() -> str:
     """
     获取当前终端名称(自动适配 Windows/Linux/Mac)
@@ -463,6 +497,7 @@ def execute_shell_command(
     command: str,
     compact_output: bool = False,
     cancel_token: Optional[str] = None,
+    pretty: bool = True,
 ):
     """
     Execute a shell command with cross-platform encoding support and streaming output.
@@ -474,6 +509,13 @@ def execute_shell_command(
             no "Output streaming" banner). Used by terminal V3 ``!`` prefix.
         cancel_token: If provided, register an on_cancel callback to kill the
             subprocess when the token is cancelled.
+        pretty: 消费端是否能渲染 ANSI / 是否是 TTY。
+            - ``True``(默认):TUI、交互式 CLI 等场景,允许 Rich 输出彩色命令头,
+              同时保留子进程原生输出(可能带 ANSI 色)
+            - ``False``:CloudBridge、Web、日志采集等非 TTY 场景,命令头降级为
+              纯文本,并给子进程注入 ``NO_COLOR=1`` / ``TERM=dumb`` /
+              ``FORCE_COLOR=0`` 等环境变量,让绝大多数 CLI 工具(cursor-agent、
+              git、pip、npm 等)主动以纯文本输出,避免 ANSI 色码污染下游。
     """
     user_command = command
     console = Console()
@@ -548,6 +590,11 @@ set PYTHONIOENCODING=utf-8
         env["GIT_PAGER"] = "cat"
         env["GIT_TERMINAL_PROMPT"] = "0"
 
+        # 非 TTY 消费端:显式告知子进程禁用 ANSI 色码。这样 cursor-agent、git 等
+        # CLI 启动时就不会输出彩色,从源头避免污染 CloudBridge / Web 等下游。
+        if not pretty:
+            env.update(_NO_COLOR_ENV)
+
         process = subprocess.Popen(
             command,
             stdin=subprocess.DEVNULL,
@@ -594,7 +641,7 @@ set PYTHONIOENCODING=utf-8
                     "return_code": return_code,
                 },
             )
-            _print_compact_shell_header(user_command, return_code)
+            _print_compact_shell_header(user_command, return_code, pretty=pretty)
             if merged:
                 print(merged)
             return
@@ -704,7 +751,7 @@ set PYTHONIOENCODING=utf-8
             },
         )
         if compact_output:
-            _print_compact_shell_header(user_command, 127)
+            _print_compact_shell_header(user_command, 127, pretty=pretty)
             print(f"Command not found: {user_command}")
         else:
             console.print(
@@ -721,7 +768,7 @@ set PYTHONIOENCODING=utf-8
             },
         )
         if compact_output:
-            _print_compact_shell_header(user_command, 1)
+            _print_compact_shell_header(user_command, 1, pretty=pretty)
             print(str(e))
         else:
             console.print(

auto_coder-3.0.46/src/autocoder/terminal_core/cloud_block_command.py

@@ -0,0 +1,86 @@
+"""
+Block command parser and registry for `#[cmd] args` syntax.
+
+This module provides the foundation for structured remote primitives
+that the Dashboard can invoke on CLI instances. Each block command
+is identified by `#[<identifier>]` followed by optional arguments.
+
+Examples:
+    #[file_read] README.md
+    #[ls] src/
+    #[grep] pattern *.py
+"""
+
+import re
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from autocoder.terminal_core.cloud_file_uploader import CloudFileUploader
+
+BLOCK_COMMAND_RE = re.compile(
+    r"^#\[([A-Za-z_][A-Za-z0-9_]*)\](?:\s+(.*))?$", re.DOTALL
+)
+
+
+@dataclass
+class ParsedBlockCommand:
+    cmd: str
+    args: str
+
+
+def parse_block_command(prompt_text: str) -> Optional[ParsedBlockCommand]:
+    """Parse ``#[cmd] args`` from the start of *prompt_text*.
+
+    Returns ``None`` when the text does not match the block-command syntax.
+    """
+    text = prompt_text.strip()
+    m = BLOCK_COMMAND_RE.match(text)
+    if not m:
+        return None
+    return ParsedBlockCommand(cmd=m.group(1), args=(m.group(2) or "").strip())
+
+
+@dataclass
+class CommandOutcome:
+    """Unified result container for block-command handlers.
+
+    *text*     – human-readable summary (written to ``resultText``)
+    *payload*  – structured data (merged into ``resultPayloads``)
+    *files*    – IDs of files already uploaded & registered via the uploader
+    """
+
+    text: str = ""
+    payload: Dict[str, Any] = field(default_factory=dict)
+    files: List[str] = field(default_factory=list)
+
+    @classmethod
+    def text_only(cls, s: str) -> "CommandOutcome":
+        return cls(text=s)
+
+
+@dataclass
+class CommandContext:
+    """Runtime context passed to block-command handlers."""
+
+    run_id: str
+    uploader: Optional["CloudFileUploader"] = None
+
+
+BlockHandler = Callable[..., CommandOutcome]
+
+
+class BlockCommandRegistry:
+    """Registry of ``#[cmd]`` handlers."""
+
+    def __init__(self) -> None:
+        self._handlers: Dict[str, BlockHandler] = {}
+
+    def register(self, cmd: str, handler: BlockHandler) -> None:
+        self._handlers[cmd] = handler
+
+    def has(self, cmd: str) -> bool:
+        return cmd in self._handlers
+
+    def get(self, cmd: str) -> Optional[BlockHandler]:
+        return self._handlers.get(cmd)

{auto_coder-3.0.44 → auto_coder-3.0.46}/src/autocoder/terminal_core/cloud_bridge.py

@@ -456,6 +456,7 @@ class CloudBridge:
         result_text: Optional[str] = None,
         error_text: Optional[str] = None,
         usage_details: Optional[List[Dict[str, Any]]] = None,
+        result_payloads: Optional[Dict[str, Any]] = None,
     ):
         body: Dict[str, Any] = {"status": status}
         if result_text is not None:
@@ -464,6 +465,8 @@ class CloudBridge:
             body["errorText"] = error_text
         if usage_details:
             body["usageDetails"] = usage_details
+        if result_payloads:
+            body["resultPayloads"] = result_payloads
         try:
             await asyncio.get_event_loop().run_in_executor(
                 None,
@@ -685,17 +688,29 @@ class CloudBridge:
             self._run_cancel_tokens.pop(run.id, None)
 
     async def _process_command_run(self, run: PendingRun, cancel_token: Optional[str] = None):
-        """处理斜杠命令类型的 run（如 /commit），在线程池中执行后回传结果。"""
+        """处理斜杠命令类型的 run（如 /commit、#[file_read]），在线程池中执行后回传结果。"""
         cancel_token = cancel_token or f"cloud-run-{run.id}"
         global_cancel.register_token(cancel_token)
         self._run_cancel_tokens[run.id] = cancel_token
 
         try:
+            from autocoder.terminal_core.cloud_block_command import CommandContext
+            from autocoder.terminal_core.cloud_file_uploader import CloudFileUploader
+
+            ctx = CommandContext(
+                run_id=run.id,
+                uploader=CloudFileUploader(
+                    session=self._session,
+                    base_url=self._config.base_url,
+                    run_id=run.id,
+                ),
+            )
+
             loop = asyncio.get_event_loop()
             cmd_result = await loop.run_in_executor(
                 None,
                 lambda: self._command_dispatcher.dispatch(
-                    run.prompt_text, cancel_token=cancel_token
+                    run.prompt_text, cancel_token=cancel_token, context=ctx
                 ),
             )
             if global_cancel.is_requested(cancel_token):
@@ -705,8 +720,12 @@ class CloudBridge:
                     run.id, "FAILED", error_text=cmd_result.error_text
                 )
             else:
+                outcome = cmd_result.outcome
                 await self._report_result(
-                    run.id, "COMPLETED", result_text=cmd_result.result_text or ""
+                    run.id,
+                    "COMPLETED",
+                    result_text=cmd_result.result_text or "",
+                    result_payloads=outcome.payload if outcome and outcome.payload else None,
                 )
         except Exception as e:
             logger.error(f"CloudBridge command run {run.id} failed: {e}")

{auto_coder-3.0.44 → auto_coder-3.0.46}/src/autocoder/terminal_core/cloud_command_dispatcher.py

@@ -1,12 +1,12 @@
 """
 CloudCommandDispatcher - 云端命令分发器
 
-可扩展的斜杠命令处理器，用于处理从云端下发的 /commit 等命令。
-新增命令只需注册一个 handler 即可。
+可扩展的命令处理器，用于处理从云端下发的 /commit、!shell、$workflow
+以及 #[cmd] 块指令等命令。新增命令只需注册一个 handler 即可。
 
-每个 handler 签名: (args: str) -> str
-  - args: 命令后面的参数部分（已 strip）
-  - 返回: 结果文本，回传给云端
+handler 签名:
+  - 斜杠/前缀命令: (args: str, **kwargs) -> str
+  - 块指令: (args: str, *, cancel_token, context) -> CommandOutcome
 """
 
 import json
@@ -17,6 +17,13 @@ from typing import Any, Callable, Dict, Optional
 
 from loguru import logger
 
+from autocoder.terminal_core.cloud_block_command import (
+    BlockCommandRegistry,
+    CommandContext,
+    CommandOutcome,
+    parse_block_command,
+)
+
 
 CommandHandler = Callable[..., str]
 
@@ -26,6 +33,7 @@ class CommandResult:
     handled: bool
     result_text: str = ""
     error_text: str = ""
+    outcome: Optional[CommandOutcome] = None
 
 
 class CloudCommandDispatcher:
@@ -45,6 +53,7 @@ class CloudCommandDispatcher:
     def __init__(self):
         self._handlers: Dict[str, CommandHandler] = {}
         self._prefix_handlers: Dict[str, CommandHandler] = {}
+        self._block_registry = BlockCommandRegistry()
 
     def register(self, command: str, handler: CommandHandler) -> None:
         self._handlers[command] = handler
@@ -53,6 +62,10 @@ class CloudCommandDispatcher:
         """注册前缀命令（如 '!' 和 '$'），整条文本去掉前缀后作为 args。"""
         self._prefix_handlers[prefix] = handler
 
+    def register_block(self, cmd: str, handler: Any) -> None:
+        """注册 ``#[cmd]`` 块指令 handler。"""
+        self._block_registry.register(cmd, handler)
+
     def unregister(self, command: str) -> None:
         self._handlers.pop(command, None)
         self._prefix_handlers.pop(command, None)
@@ -63,6 +76,10 @@ class CloudCommandDispatcher:
 
     def is_command(self, prompt_text: str) -> bool:
         text = prompt_text.strip()
+        # Block commands: #[cmd] args
+        parsed = parse_block_command(text)
+        if parsed is not None and self._block_registry.has(parsed.cmd):
+            return True
         for prefix in self._prefix_handlers:
             if text.startswith(prefix):
                 return True
@@ -72,17 +89,45 @@ class CloudCommandDispatcher:
         return cmd_word in self._handlers
 
     def dispatch(
-        self, prompt_text: str, cancel_token: Optional[str] = None
+        self,
+        prompt_text: str,
+        cancel_token: Optional[str] = None,
+        context: Optional[CommandContext] = None,
     ) -> CommandResult:
         text = prompt_text.strip()
 
+        # Block commands take priority: #[cmd] args
+        parsed = parse_block_command(text)
+        if parsed is not None:
+            handler = self._block_registry.get(parsed.cmd)
+            if handler is not None:
+                logger.info(f"CloudCommandDispatcher: executing block #{parsed.cmd}")
+                try:
+                    outcome = handler(
+                        parsed.args,
+                        cancel_token=cancel_token,
+                        context=context,
+                    )
+                    return CommandResult(
+                        handled=True,
+                        result_text=outcome.text,
+                        outcome=outcome,
+                    )
+                except Exception as e:
+                    logger.error(f"CloudCommandDispatcher: block #{parsed.cmd} failed: {e}")
+                    return CommandResult(handled=True, error_text=str(e))
+
         for prefix, handler in self._prefix_handlers.items():
             if text.startswith(prefix):
                 args = text[len(prefix):].strip()
                 logger.info(f"CloudCommandDispatcher: executing prefix '{prefix}'")
                 try:
                     result_text = handler(args, cancel_token=cancel_token)
-                    return CommandResult(handled=True, result_text=result_text)
+                    return CommandResult(
+                        handled=True,
+                        result_text=result_text,
+                        outcome=CommandOutcome.text_only(result_text),
+                    )
                 except Exception as e:
                     logger.error(f"CloudCommandDispatcher: prefix '{prefix}' failed: {e}")
                     return CommandResult(handled=True, error_text=str(e))
@@ -101,7 +146,11 @@ class CloudCommandDispatcher:
         logger.info(f"CloudCommandDispatcher: executing {cmd_word}")
         try:
             result_text = handler(args)
-            return CommandResult(handled=True, result_text=result_text)
+            return CommandResult(
+                handled=True,
+                result_text=result_text,
+                outcome=CommandOutcome.text_only(result_text),
+            )
         except Exception as e:
             logger.error(f"CloudCommandDispatcher: {cmd_word} failed: {e}")
             return CommandResult(handled=True, error_text=str(e))
@@ -114,6 +163,7 @@ class CloudCommandDispatcher:
         self.register("/tunnel", _handle_tunnel)
         self.register_prefix("!", _handle_shell)
         self.register_prefix("$", _handle_workflow_shortcut)
+        self.register_block("file_read", _handle_file_read)
 
 
 def _load_cloud_connection_config() -> tuple[str, str]:
@@ -961,3 +1011,44 @@ def _handle_tunnel(args: str) -> str:
         "  /tunnel stop <tunnel_id>\n"
         "  /tunnel list"
     )
+
+
+# ── #[file_read] ─────────────────────────────────────────
+
+
+def _handle_file_read(
+    args: str,
+    *,
+    cancel_token: Optional[str] = None,
+    context: Optional[CommandContext] = None,
+) -> CommandOutcome:
+    """Handle ``#[file_read] <path>``: read a local file and upload it."""
+    if not args:
+        return CommandOutcome.text_only("Usage: #[file_read] <path>")
+    if context is None or context.uploader is None:
+        return CommandOutcome.text_only(
+            "File read requires cloud context (not available in this environment)."
+        )
+    path = args.strip()
+    if not os.path.exists(path):
+        return CommandOutcome.text_only(f"File not found: {path}")
+    if not os.path.isfile(path):
+        return CommandOutcome.text_only(f"Not a file: {path}")
+    try:
+        uploaded = context.uploader.upload(path)
+        return CommandOutcome(
+            text=f"File uploaded: {uploaded.original_name} ({uploaded.size_bytes} bytes)",
+            payload={
+                "result_type": "file_read",
+                "source_path": path,
+                "uploaded": {
+                    "id": uploaded.id,
+                    "original_name": uploaded.original_name,
+                    "size_bytes": uploaded.size_bytes,
+                    "content_type": uploaded.content_type,
+                },
+            },
+            files=[uploaded.id],
+        )
+    except Exception as e:
+        return CommandOutcome.text_only(f"Upload failed: {e}")

auto_coder-3.0.46/src/autocoder/terminal_core/cloud_file_uploader.py

@@ -0,0 +1,122 @@
+"""
+CloudFileUploader – upload local files to auto-coder.chat cloud storage.
+
+Three-step protocol per file:
+  1. POST /api/client/runs/{id}/uploads/init   → validate & get mode
+  2. POST /api/client/runs/{id}/uploads/proxy   → multipart upload (server proxies to blob)
+  3. POST /api/client/runs/{id}/files            → register LiteRunFile record(s)
+
+Step 3 supports batch registration (multiple files in one call).
+"""
+
+import mimetypes
+import os
+from dataclasses import dataclass
+from typing import Any, Dict, List
+
+from loguru import logger
+from requests import Session
+
+MAX_UPLOAD_SIZE = 10 * 1024 * 1024  # 10 MB – must match server-side limit
+
+
+@dataclass
+class UploadedFile:
+    id: str
+    original_name: str
+    size_bytes: int
+    content_type: str
+
+
+class CloudFileUploader:
+    def __init__(self, session: Session, base_url: str, run_id: str) -> None:
+        self._session = session
+        self._base_url = base_url.rstrip("/")
+        self._run_id = run_id
+
+    def _url(self, path: str) -> str:
+        return f"{self._base_url}{path}"
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def upload(self, file_path: str) -> UploadedFile:
+        """Upload a single file and register it."""
+        return self.upload_batch([file_path])[0]
+
+    def upload_batch(self, file_paths: List[str]) -> List[UploadedFile]:
+        """Upload multiple files (init + proxy each), then batch-register."""
+        stored: List[Dict[str, Any]] = []
+        for p in file_paths:
+            meta = self._upload_one(p)
+            stored.append(meta)
+
+        resp = self._session.post(
+            self._url(f"/api/client/runs/{self._run_id}/files"),
+            json={"files": stored},
+        )
+        resp.raise_for_status()
+        data = resp.json().get("files", [])
+        return [
+            UploadedFile(
+                id=f["id"],
+                original_name=f["originalName"],
+                size_bytes=f["sizeBytes"],
+                content_type=f["contentType"],
+            )
+            for f in data
+        ]
+
+    # ------------------------------------------------------------------
+    # Internal
+    # ------------------------------------------------------------------
+
+    def _upload_one(self, path: str) -> Dict[str, Any]:
+        size = os.path.getsize(path)
+        if size > MAX_UPLOAD_SIZE:
+            raise ValueError(
+                f"File too large ({size} bytes, limit {MAX_UPLOAD_SIZE}): {path}"
+            )
+
+        filename = os.path.basename(path)
+        content_type, _ = mimetypes.guess_type(path)
+        content_type = content_type or "application/octet-stream"
+
+        logger.info(
+            f"CloudFileUploader: uploading {filename} "
+            f"({size} bytes, {content_type})"
+        )
+
+        # 1. init
+        init_resp = self._session.post(
+            self._url(f"/api/client/runs/{self._run_id}/uploads/init"),
+            json={
+                "filename": filename,
+                "contentType": content_type,
+                "sizeBytes": size,
+            },
+        )
+        init_resp.raise_for_status()
+
+        # 2. proxy upload (multipart)
+        # Session-level headers carry Content-Type: application/json. When
+        # we call session.post(..., files=...), `requests` MERGES call-level
+        # headers with session headers, so a Content-Type already set on the
+        # session is kept and `files=` never gets a chance to inject its
+        # own `multipart/form-data; boundary=...` header — the request goes
+        # out as application/json and the server rejects the multipart parse.
+        #
+        # The documented way to drop a session-level header for a single call
+        # is to pass the key with value `None` at call level:
+        #   https://requests.readthedocs.io/en/master/user/advanced/
+        # ("Sometimes you'll want to omit session-level keys ... set that
+        # key's value to None in the method-level parameter.")
+        with open(path, "rb") as f:
+            proxy_resp = self._session.post(
+                self._url(f"/api/client/runs/{self._run_id}/uploads/proxy"),
+                files={"file": (filename, f, content_type)},
+                headers={"Content-Type": None},
+            )
+        proxy_resp.raise_for_status()
+        return proxy_resp.json()