minimax-code-sdk 0.1.0__py3-none-any.whl

minimax_code/__init__.py

@@ -0,0 +1,66 @@
+"""Python SDK for driving the local MiniMax Code (``mcode``) agent."""
+
+from .client import MCode
+from .errors import (
+    MCODE_EXEC_EXIT_CODES,
+    MCodeAbortError,
+    MCodeError,
+    MCodeInvocationError,
+    MCodeNotFoundError,
+    MCodeProtocolError,
+    MCodeRunError,
+    MCodeVersionError,
+    ThreadBusyError,
+)
+from .sync import SyncMCode, SyncThread
+from .thread import StreamedTurn, Thread
+from .types import (
+    AgentMessageItem,
+    ExecError,
+    ExecItem,
+    ExecResult,
+    MCodeOptions,
+    ModelIdentity,
+    ReasoningItem,
+    RunOptions,
+    ThreadEvent,
+    ThreadItem,
+    ThreadOptions,
+    ToolCallItem,
+    Turn,
+    Usage,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "MCODE_EXEC_EXIT_CODES",
+    "AgentMessageItem",
+    "ExecError",
+    "ExecItem",
+    "ExecResult",
+    "MCode",
+    "MCodeAbortError",
+    "MCodeError",
+    "MCodeInvocationError",
+    "MCodeNotFoundError",
+    "MCodeOptions",
+    "MCodeProtocolError",
+    "MCodeRunError",
+    "MCodeVersionError",
+    "ModelIdentity",
+    "ReasoningItem",
+    "RunOptions",
+    "StreamedTurn",
+    "SyncMCode",
+    "SyncThread",
+    "Thread",
+    "ThreadBusyError",
+    "ThreadEvent",
+    "ThreadItem",
+    "ThreadOptions",
+    "ToolCallItem",
+    "Turn",
+    "Usage",
+    "__version__",
+]

minimax_code/_args.py

@@ -0,0 +1,90 @@
+"""Builds ``mcode exec`` argv. Mirrors ``packages/code-sdk/src/args.ts``."""
+
+from __future__ import annotations
+
+import os
+
+from .errors import MCodeInvocationError
+from .types import RunOptions, ThreadOptions
+
+_PERMISSIONS = {"smart", "full", "off"}
+_MODES = {"standard", "lightweight"}
+_PROMPT_MODES = {"tui", "coding", "work"}
+MAX_TIMEOUT_MS = 2**31 - 1
+
+
+def validate_thread_options(options: ThreadOptions, resuming: bool) -> None:
+    if options.permission is not None and options.permission not in _PERMISSIONS:
+        raise MCodeInvocationError(
+            f"permission must be smart, full or off; received {options.permission!r}."
+        )
+    if options.mode is not None and options.mode not in _MODES:
+        raise MCodeInvocationError(
+            f"mode must be standard or lightweight; received {options.mode!r}."
+        )
+    if resuming and options.mode == "lightweight":
+        raise MCodeInvocationError(
+            'mode "lightweight" requires a new Thread; it cannot be resumed.'
+        )
+    if options.prompt_mode is not None and options.prompt_mode not in _PROMPT_MODES:
+        raise MCodeInvocationError(
+            f"prompt_mode must be tui, coding or work; received {options.prompt_mode!r}."
+        )
+
+
+def _positive_int(value: object) -> bool:
+    return isinstance(value, int) and not isinstance(value, bool) and value > 0
+
+
+def validate_run_options(options: RunOptions) -> None:
+    if options.timeout_ms is not None and (
+        not _positive_int(options.timeout_ms) or options.timeout_ms > MAX_TIMEOUT_MS
+    ):
+        raise MCodeInvocationError(
+            f"timeout_ms must be a positive integer no greater than {MAX_TIMEOUT_MS}."
+        )
+    if options.max_steps is not None and not _positive_int(options.max_steps):
+        raise MCodeInvocationError("max_steps must be a positive integer.")
+
+
+def build_exec_args(
+    *,
+    thread: ThreadOptions,
+    session_id: str | None,
+    run: RunOptions,
+    config_path: str | None = None,
+    system_prompt_file: str | None = None,
+    append_system_prompt_file: str | None = None,
+) -> list[str]:
+    """The prompt travels over stdin and system prompts through temp files; values use the
+    ``--flag=value`` form so a value starting with ``-`` is never parsed as a flag."""
+    args = [
+        "exec",
+        "--output-format=stream-json",
+        "--input=-",
+        "--input-format=json",
+        f"--cwd={os.path.abspath(thread.cwd or os.getcwd())}",
+    ]
+
+    def push(flag: str, value: str | None) -> None:
+        if value is not None:
+            args.append(f"{flag}={value}")
+
+    push("--model", thread.model)
+    push("--effort", thread.effort)
+    push("--permission", thread.permission)
+    push("--prompt-mode", thread.prompt_mode)
+    push("--config", config_path)
+    if session_id is None:
+        push("--mode", thread.mode)
+    else:
+        push("--session", session_id)
+    push("--system-prompt-file", system_prompt_file)
+    push("--append-system-prompt-file", append_system_prompt_file)
+    for file in run.files:
+        push("--file", file)
+    if run.timeout_ms is not None:
+        push("--timeout", f"{run.timeout_ms}ms")
+    if run.max_steps is not None:
+        push("--max-steps", str(run.max_steps))
+    return args

minimax_code/_cli.py

@@ -0,0 +1,205 @@
+"""Locates and version-checks the ``mcode`` CLI. Mirrors ``packages/code-sdk/src/cli-resolver.ts``
+and the Windows launcher handling of ``project-bin.ts``: the SDK never starts the CLI through a
+shell, so Windows ``.cmd`` launchers are followed to the JS entry and Node runtime they run.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import re
+import shutil
+import sys
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+from .errors import MCODE_INSTALL_HINT, MCodeNotFoundError, MCodeVersionError
+
+MIN_CLI_VERSION = (0, 6, 3)
+_JS_SUFFIXES = (".js", ".mjs", ".cjs")
+#: Windows files that CreateProcess runs directly, without cmd.exe.
+_WINDOWS_NATIVE = (".exe", ".com")
+#: Lines of the Windows root launcher written by the official installer and CLI self-update.
+_VERSIONED_POINTER_LINE = 'SET /P MCODE_RELEASE=<"%~dp0current"'
+_VERSIONED_CALL_LINE = 'CALL "%~dp0releases\\%MCODE_RELEASE%\\.mcode-launcher.cmd"'
+#: Same release-key rule the root launcher enforces before following the pointer.
+_RELEASE_KEY = re.compile(r"[0-9A-Za-z][0-9A-Za-z._-]*")
+#: JS entry in an npm / pnpm ``.cmd`` shim or an installer release launcher.
+_CMD_SHIM_ENTRY = re.compile(r'"%~?dp0%?\\?([^"%]+\.(?:c|m)?js)"', re.IGNORECASE)
+#: JS entry in an npm / pnpm POSIX shell or PowerShell shim.
+_SHELL_SHIM_ENTRY = re.compile(r'"\$basedir[\\/]([^"$]+\.(?:c|m)?js)"')
+#: The pinned runtime of an installer release launcher: ``"<node>" "%~dp0<entry>" %*``.
+_CMD_RUNTIME = re.compile(r'^"([^"%]+)"[ \t]+"%~dp0', re.MULTILINE)
+_SHIM_HEAD_BYTES = 4096
+
+
+@dataclass(frozen=True)
+class ResolvedCli:
+    """How to start the CLI."""
+
+    path: str
+    """The executable, or the JS entry that runs with Node."""
+    node: str | None = None
+    """Node runtime for a JS entry; ``None`` uses ``node`` from ``PATH``."""
+    launcher: str | None = None
+    """Windows installer root launcher. Its release pointer is followed again before every run, so
+    a CLI self-update between Turns is picked up."""
+
+    def command(self, args: list[str]) -> list[str]:
+        if self.launcher is not None:
+            current = _follow_versioned_launcher(self.launcher)
+            if current is None:
+                raise MCodeNotFoundError(
+                    f"{self.launcher} no longer points to a usable release. "
+                    "Pass the CLI's JS entry as MCodeOptions(bin=...)."
+                )
+            return current.command(args)
+        if self.path.lower().endswith(_JS_SUFFIXES):
+            return [self.node or shutil.which("node") or "node", self.path, *args]
+        return [self.path, *args]
+
+
+def resolve_cli(
+    bin: str | None, env: Mapping[str, str], platform: str = sys.platform
+) -> ResolvedCli:
+    """Explicit ``bin`` → ``$MCODE_BIN`` → ``mcode`` on ``PATH``."""
+    explicit = bin or _env(env, "MCODE_BIN", platform) or None
+    if explicit:
+        path = os.path.abspath(os.path.expanduser(explicit))
+        if not os.path.isfile(path):
+            source = "bin" if bin else "MCODE_BIN"
+            raise MCodeNotFoundError(f"mcode CLI from {source} does not exist: {path}")
+        return _from_executable(path, platform)
+    found = shutil.which("mcode", path=_env(env, "PATH", platform) or os.defpath)
+    if not found:
+        raise MCodeNotFoundError(
+            "Could not find the mcode CLI on PATH. Install it with "
+            f"`{MCODE_INSTALL_HINT}`, set MCODE_BIN, or pass MCodeOptions(bin=...)."
+        )
+    return _from_executable(found, platform)
+
+
+def _from_executable(path: str, platform: str) -> ResolvedCli:
+    extension = os.path.splitext(path)[1].lower()
+    if extension in _JS_SUFFIXES or platform != "win32" or extension in _WINDOWS_NATIVE:
+        return ResolvedCli(path)
+    # A batch file or shell shim would need cmd.exe and its quoting rules, and cancelling it would
+    # stop only cmd.exe and leave the CLI running. Run the JS entry behind it instead.
+    try:
+        head = _read_head(path)
+    except OSError:
+        head = ""
+    if extension in (".cmd", ".bat"):
+        resolved = resolve_cmd_launcher(head, path)
+    else:
+        entry = _parse_shim(_SHELL_SHIM_ENTRY, head, path)
+        resolved = ResolvedCli(entry, node=_adjacent_node(path)) if entry else None
+    if resolved is None:
+        raise MCodeNotFoundError(
+            f"Found {path}, but could not determine the JS entry it runs. "
+            "Pass the CLI's JS entry as MCodeOptions(bin=...) or MCODE_BIN."
+        )
+    return resolved
+
+
+def resolve_cmd_launcher(content: str, launcher: str) -> ResolvedCli | None:
+    """Resolves a Windows ``.cmd`` launcher: an npm / pnpm shim, or the installer's root
+    launcher, whose release is looked up again before every run."""
+    entry = _parse_shim(_CMD_SHIM_ENTRY, content, launcher)
+    if entry:
+        return ResolvedCli(entry, node=_adjacent_node(launcher))
+    versioned = _VERSIONED_POINTER_LINE in content and _VERSIONED_CALL_LINE in content
+    if versioned and _follow_versioned_launcher(launcher) is not None:
+        return ResolvedCli(launcher, launcher=launcher)
+    return None
+
+
+def _follow_versioned_launcher(launcher: str) -> ResolvedCli | None:
+    """``<prefix>\\mcode.cmd`` reads the release key from ``<prefix>\\current`` and calls
+    ``<prefix>\\releases\\<release>\\.mcode-launcher.cmd``, which runs a pinned Node runtime."""
+    prefix = os.path.dirname(launcher)
+    try:
+        with open(os.path.join(prefix, "current"), encoding="utf-8") as handle:
+            release = handle.read().strip()
+        if not _RELEASE_KEY.fullmatch(release):
+            return None
+        release_launcher = os.path.join(prefix, "releases", release, ".mcode-launcher.cmd")
+        content = _read_head(release_launcher)
+    except OSError:
+        return None
+    entry = _parse_shim(_CMD_SHIM_ENTRY, content, release_launcher)
+    if entry is None:
+        return None
+    runtime = _CMD_RUNTIME.search(content)
+    node = runtime.group(1) if runtime and os.path.isfile(runtime.group(1)) else None
+    return ResolvedCli(entry, node=node)
+
+
+def _parse_shim(pattern: re.Pattern[str], content: str, shim: str) -> str | None:
+    match = pattern.search(content)
+    if not match:
+        return None
+    parts = [part for part in re.split(r"[\\/]", match.group(1)) if part]
+    entry = os.path.normpath(os.path.join(os.path.dirname(shim), *parts))
+    return entry if os.path.isfile(entry) else None
+
+
+def _adjacent_node(shim: str) -> str | None:
+    """npm shims prefer a ``node.exe`` next to them over ``PATH``."""
+    candidate = os.path.join(os.path.dirname(shim), "node.exe")
+    return candidate if os.path.isfile(candidate) else None
+
+
+def _read_head(path: str) -> str:
+    with open(path, "rb") as handle:
+        return handle.read(_SHIM_HEAD_BYTES).decode("utf-8", "replace")
+
+
+def _env(env: Mapping[str, str], key: str, platform: str) -> str | None:
+    """Environment names are case-insensitive on Windows (``Path``)."""
+    if platform != "win32":
+        return env.get(key)
+    return next((value for name, value in env.items() if name.upper() == key), None)
+
+
+def parse_version(text: str) -> tuple[int, int, int] | None:
+    match = re.search(r"(\d+)\.(\d+)\.(\d+)", text)
+    if not match:
+        return None
+    major, minor, patch = (int(part) for part in match.groups())
+    return (major, minor, patch)
+
+
+async def check_cli_version(cli: ResolvedCli, env: Mapping[str, str]) -> str:
+    try:
+        proc = await asyncio.create_subprocess_exec(
+            *cli.command(["--version"]),
+            stdin=asyncio.subprocess.DEVNULL,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            env=dict(env),
+        )
+        out, err = await asyncio.wait_for(proc.communicate(), timeout=30)
+    except (OSError, asyncio.TimeoutError) as error:
+        raise MCodeNotFoundError(f"Could not run `{cli.path} --version`: {error}") from error
+    if proc.returncode != 0:
+        raise MCodeVersionError(
+            f"`mcode --version` failed ({proc.returncode}); cannot verify CLI compatibility.",
+            exit_code=proc.returncode,
+            stderr=err.decode("utf-8", "replace"),
+        )
+    text = out.decode("utf-8", "replace")
+    version = parse_version(text)
+    if version is None:
+        raise MCodeVersionError(f"Could not read the mcode version from: {text.strip()!r}.")
+    if version < MIN_CLI_VERSION:
+        minimum = ".".join(map(str, MIN_CLI_VERSION))
+        found = ".".join(map(str, version))
+        raise MCodeVersionError(
+            f"mcode {found} is older than the minimum {minimum} required by minimax-code-sdk. "
+            f"Upgrade with `{MCODE_INSTALL_HINT}`."
+        )
+    return ".".join(map(str, version))
+
+
+__all__ = ["ResolvedCli", "check_cli_version", "resolve_cli", "resolve_cmd_launcher"]

minimax_code/_items.py

@@ -0,0 +1,71 @@
+"""Folds ``item.*`` events into SDK items. Mirrors ``packages/code-sdk/src/items.ts``."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any
+
+from .types import AgentMessageItem, ReasoningItem, ThreadEvent, ThreadItem, ToolCallItem
+
+
+@dataclass
+class _State:
+    type: str
+    text: str = ""
+    tool_call: dict[str, Any] | None = None
+    completed: bool = False
+    snapshot: str = ""
+
+
+class ItemAccumulator:
+    def __init__(self) -> None:
+        self._states: dict[str, _State] = {}
+
+    def apply(self, event: ThreadEvent) -> bool:
+        """Applies one event. Returns False for a duplicate snapshot ``item.updated``."""
+        if event["type"] not in ("item.started", "item.updated", "item.completed"):
+            return True
+        item = event.get("item")
+        if item is None:
+            return True
+        delta = item.get("contentDelta")
+        snapshot = json.dumps(item, sort_keys=True) if delta is None else ""
+        state = self._states.get(item["id"])
+        if (
+            state is not None
+            and event["type"] == "item.updated"
+            and snapshot
+            and state.snapshot == snapshot
+            and not state.completed
+        ):
+            return False
+        if state is None:
+            state = _State(type=item["type"])
+            self._states[item["id"]] = state
+        state.snapshot = snapshot
+        if delta is not None:
+            state.text += delta
+        if "content" in item:
+            state.text = item["content"]
+        if "toolCall" in item:
+            state.tool_call = item["toolCall"]
+        if event["type"] == "item.completed":
+            state.completed = True
+        return True
+
+    def items(self) -> list[ThreadItem]:
+        out: list[ThreadItem] = []
+        for item_id, s in self._states.items():
+            incomplete = not s.completed
+            if s.type == "agent_message":
+                out.append(AgentMessageItem(id=item_id, text=s.text, incomplete=incomplete))
+            elif s.type == "reasoning":
+                out.append(ReasoningItem(id=item_id, text=s.text, incomplete=incomplete))
+            elif s.type == "tool_call":
+                out.append(
+                    ToolCallItem(
+                        id=item_id, tool_call=s.tool_call or {"id": item_id}, incomplete=incomplete
+                    )
+                )
+        return out

minimax_code/_protocol.py

@@ -0,0 +1,56 @@
+"""Parses stdout lines. Mirrors ``packages/code-sdk/src/protocol.ts``."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, cast
+
+from .errors import MCodeProtocolError, MCodeVersionError
+from .types import ThreadEvent
+
+SUPPORTED_SCHEMA_VERSION = 1
+
+
+def _truncate(text: str) -> str:
+    return text if len(text) <= 200 else text[:200] + "…"
+
+
+def parse_event_line(line: str) -> ThreadEvent | None:
+    text = line.strip()
+    if not text:
+        return None
+    try:
+        value: Any = json.loads(text)
+    except json.JSONDecodeError as error:
+        raise MCodeProtocolError(f"mcode stdout is not JSON: {_truncate(text)}") from error
+    if not isinstance(value, dict):
+        raise MCodeProtocolError(f"mcode stdout line is not a JSON object: {_truncate(text)}")
+    if value.get("schemaVersion") != SUPPORTED_SCHEMA_VERSION:
+        raise MCodeVersionError(
+            f"Unsupported mcode event schemaVersion {value.get('schemaVersion')!r}; "
+            f"this SDK supports {SUPPORTED_SCHEMA_VERSION}."
+        )
+    if not isinstance(value.get("type"), str) or not isinstance(value.get("sessionId"), str):
+        raise MCodeProtocolError(f"mcode event is missing type or sessionId: {_truncate(text)}")
+    kind: str = value["type"]
+    if kind.startswith("item."):
+        item = value.get("item")
+        if not (
+            isinstance(item, dict)
+            and isinstance(item.get("id"), str)
+            and isinstance(item.get("type"), str)
+        ):
+            raise MCodeProtocolError(f"mcode {kind} event has an invalid item: {_truncate(text)}")
+    if kind == "exec.completed":
+        result = value.get("result")
+        if not (
+            isinstance(result, dict)
+            and result.get("schemaVersion") == SUPPORTED_SCHEMA_VERSION
+            and isinstance(result.get("status"), str)
+            and isinstance(result.get("sessionId"), str)
+            and isinstance(result.get("turnId"), str)
+        ):
+            raise MCodeProtocolError(
+                f"mcode exec.completed has an invalid result: {_truncate(text)}"
+            )
+    return cast(ThreadEvent, value)

minimax_code/client.py

@@ -0,0 +1,76 @@
+"""Entry point. Mirrors ``packages/code-sdk/src/mcode.ts``."""
+
+from __future__ import annotations
+
+import asyncio
+import dataclasses
+import os
+
+from ._args import validate_thread_options
+from ._cli import ResolvedCli, check_cli_version, resolve_cli
+from .errors import MCodeInvocationError
+from .thread import Thread, ThreadHost
+from .types import MCodeOptions, ThreadOptions
+
+
+class MCode:
+    """One client resolves and version-checks the CLI once, then starts Threads."""
+
+    def __init__(self, options: MCodeOptions | None = None) -> None:
+        self._options = options or MCodeOptions()
+        self._cli: ResolvedCli | None = None
+        self._lock: asyncio.Lock | None = None
+        config = self._options.config_path
+        self._host = ThreadHost(
+            config_path=os.path.abspath(config) if config else None,
+            child_env=self._child_env,
+            prepare_cli=self._prepare_cli,
+        )
+
+    def start_thread(self, options: ThreadOptions | None = None) -> Thread:
+        """Starts a new Thread. The Session is created by its first Turn.
+
+        ``ThreadOptions.cwd`` defaults to the current working directory and is resolved now, so a
+        later ``os.chdir()`` does not move the Thread to another workspace.
+        """
+        options = options or ThreadOptions()
+        validate_thread_options(options, resuming=False)
+        return Thread(self._host, _with_absolute_cwd(options), None)
+
+    def resume_thread(self, thread_id: str, options: ThreadOptions | None = None) -> Thread:
+        """Continues an existing Session, for example one persisted from ``thread.id``.
+
+        Pass the same ``ThreadOptions.cwd`` the Session was created with. When ``cwd`` is omitted
+        the current working directory at this call is used, and the CLI rejects a Session whose
+        workspace differs (``MCodeRunError`` with "belongs to workspace ...").
+        """
+        if not isinstance(thread_id, str) or not thread_id.strip():
+            raise MCodeInvocationError("resume_thread requires a non-empty Session id.")
+        options = options or ThreadOptions()
+        validate_thread_options(options, resuming=True)
+        return Thread(self._host, _with_absolute_cwd(options), thread_id.strip())
+
+    def _child_env(self) -> dict[str, str]:
+        env = dict(self._options.env if self._options.env is not None else os.environ)
+        if self._options.data_dir is not None:
+            env["MINIMAX_DATA_DIR"] = os.path.abspath(self._options.data_dir)
+        return env
+
+    async def _prepare_cli(self) -> ResolvedCli:
+        if self._cli is not None:
+            return self._cli
+        if self._lock is None:
+            self._lock = asyncio.Lock()
+        async with self._lock:
+            if self._cli is None:
+                env = self._child_env()
+                cli = resolve_cli(self._options.bin, env)
+                await check_cli_version(cli, env)
+                # Only cached on success, so a later run works after installing the CLI.
+                self._cli = cli
+            return self._cli
+
+
+def _with_absolute_cwd(options: ThreadOptions) -> ThreadOptions:
+    """Pins the workspace when the Thread is created; every Turn of a Session must use it."""
+    return dataclasses.replace(options, cwd=os.path.abspath(options.cwd or os.getcwd()))