feat(code-sdk): add the @minimax-ai/code-sdk TypeScript SDK

README.md

@@ -145,6 +145,7 @@ Use `mcode init .` to generate or update project guidance in `AGENTS.md`. Descri
 | Interactive TUI | `mcode [prompt]` | Explore code, continue a conversation, and review changes or permissions. |
 | Headless | `mcode exec [prompt]` | Shell scripts, CI, batch work, and evaluations. |
 | ACP | `mcode acp` | Editors and clients supporting Agent Client Protocol. |
+| TypeScript SDK | [`@minimax-ai/code-sdk`](packages/code-sdk/README.md) | Drive `mcode exec` from Node.js code: start, stream and resume conversations. |
 
 ### Lightweight conversations
 

README_ZH.md

@@ -145,6 +145,7 @@ mcode "Find a failing test, fix the implementation, and run the relevant tests."
 | 交互式 TUI | `mcode [prompt]` | 探索代码、持续对话、审阅修改与权限确认。 |
 | Headless | `mcode exec [prompt]` | Shell、CI、批处理与评测。 |
 | ACP | `mcode acp` | 支持 Agent Client Protocol 的编辑器与客户端。 |
+| TypeScript SDK | [`@minimax-ai/code-sdk`](packages/code-sdk/README.md) | 在 Node.js 代码中驱动 `mcode exec`：启动、流式读取和续跑对话。 |
 
 ### 轻量对话
 

docs/installation.md

@@ -37,7 +37,7 @@ For npm, use the command in the README: it explicitly selects the public registr
 
 `@latest` follows the stable npm dist-tag. For a reproducible CLI version, replace `@latest` with an exact published version such as `@0.6.9`, keeping the other options. Use Node.js 22.19+ (22.x), 24.2+ (24.x), 25, or 26 for both npm and source installations.
 
-This guide builds the 0.6.3 source preview. Workspace/local build manifests remain `private: true` to prevent accidental publishing. A source checkout may contain additional reviewed distribution changes; matching version strings alone do not establish byte-for-byte or build-provenance equivalence with the official npm tarball. Use the committed source revision and release receipt to identify a source build.
+This guide builds the 0.6.3 source preview. Workspace and local-build manifests remain `private: true` to prevent accidental publishing, except `@minimax-ai/code-sdk`. That package is public and is published only as a checked tarball (`packages/code-sdk/RELEASING.md`); `prepublishOnly` rejects `npm publish` in the package directory. A source checkout may contain additional reviewed distribution changes; matching version strings alone do not establish byte-for-byte or build-provenance equivalence with the official npm tarball. Use the committed source revision and release receipt to identify a source build.
 
 For a source build, you need Git, Node.js 22.19+ (22.x), 24.2+ (24.x), 25, or 26, and pnpm 9.12.0. Regular CI uses Node.js 24 across Linux and macOS. The weekly and manual compatibility matrix covers Node.js 22.19.0, 24.2.0, 25, and 26 on both platforms. Windows CI and source-candidate validation are temporarily paused while their checks are made reliable. Initial installation and build require access to public npm.
 

docs/open-source-status.md

@@ -13,7 +13,7 @@ The current source target is **TUI 0.6.3**. This repository contains the termina
 | Embedded mcode-tools | 0.0.4, extracted from public `@minimax-ai/code@0.3.11` | `scripts/lib/mcode-tools-artifact.mjs` |
 | Historical live-service acceptance and demo | TUI 0.3.11, recorded 2026-09-11 | `docs/verification.md`, `docs/release-audit.md`, `docs/demo.md` |
 
-The product, TUI, and root workspace use the same 0.6.3 version. The embedded tool has its own version. Workspace and local-build manifests remain `private: true` to prevent accidental npm publication. Matching version strings do not prove that this source tree reproduces the published npm tarball.
+The product, TUI, and root workspace use the same 0.6.3 version. The embedded tool has its own version. Workspace and local-build manifests remain `private: true` to prevent accidental npm publication, except `@minimax-ai/code-sdk`, the TypeScript SDK. It is published separately, only from a tarball checked by `release:check`, and `prepublishOnly` rejects `npm publish` in that package directory (see `packages/code-sdk/RELEASING.md`). Matching version strings do not prove that this source tree reproduces the published npm tarball.
 
 ## Source boundary
 

docs/releasing.md

@@ -70,7 +70,7 @@ This workflow does not publish to the npm registry or change the official instal
 
 ## Source previews
 
-The current source target is MiniMax Code 0.6.3. Workspace and local-build manifests remain `private: true` to prevent accidental npm publication. A source release, npm package, and installer are separate artifacts with separate verification.
+The current source target is MiniMax Code 0.6.3. Workspace and local-build manifests remain `private: true` to prevent accidental npm publication, except `@minimax-ai/code-sdk`. That package is public. Publish it only as the tarball checked by `packages/code-sdk` `release:check` (see `packages/code-sdk/RELEASING.md`). Its `prepublishOnly` script rejects `npm publish` run in the package directory. A source release, npm package, and installer are separate artifacts with separate verification.
 
 ## Prepare a release
 

package.json

@@ -26,6 +26,8 @@
     "check:source": "node scripts/source-inventory.mjs",
     "check:plugin": "node tools/plugins/validate-plugin.mjs",
     "test:capabilities": "node scripts/run-vitest-suite.mjs capability",
+    "test:code-sdk": "node scripts/run-vitest-suite.mjs code-sdk",
+    "typecheck:code-sdk": "pnpm --filter @minimax-ai/code-sdk run typecheck",
     "test:windows": "node scripts/run-vitest-suite.mjs windows",
     "test:artifact": "node --test test/public-artifact.test.mjs",
     "test:release-tools": "node --test test/source-sync.test.mjs",

packages/code-sdk/CHANGELOG.md

@@ -0,0 +1,28 @@
+# `@minimax-ai/code-sdk` Changelog
+
+All notable changes to `@minimax-ai/code-sdk` are documented here. The SDK is versioned
+independently of the MiniMax Code CLI; see the README compatibility table for supported CLI
+versions. The first `## X.Y.Z · YYYY-MM-DD` heading is the version being released.
+
+## 0.1.0 · 2026-10-28
+
+First public release.
+
+### Added
+
+- `MCode`, `startThread`, `resumeThread`, `thread.run()` and `thread.runStreamed()` drive
+  `mcode exec --output-format stream-json`, one CLI process per Turn.
+- CLI resolution: explicit `bin`, `@minimax-ai/code` installed next to the SDK, then `mcode` on
+  `PATH`. `resolveFromCwd` (default off) also searches `process.cwd()` and parent
+  `node_modules/.bin/mcode` directories.
+- Requires MiniMax Code CLI `0.6.3` or later (a source build of this repository is `0.6.5`) and
+  Node.js `>=22.19 <23 || >=24.2 <27`.
+- Typed errors for invocation, run, cancellation, protocol, missing CLI, version and busy Thread
+  failures, mapped from the CLI exit codes.
+- Cancellation through `AbortSignal` (`SIGTERM`, then `SIGKILL` after the CLI's 60 second shutdown
+  budget) and a `timeoutMs` backstop of `timeoutMs + 90s`.
+- ESM with a `require()`-compatible export condition; no runtime dependencies.
+
+### Not yet available
+
+- `outputSchema`, approvals, steering and forking.

packages/code-sdk/CONTRIBUTING.md

@@ -0,0 +1,45 @@
+# Contributing to `@minimax-ai/code-sdk`
+
+This package is maintained only in this repository: this is its single source, and it is not
+produced or updated by source synchronization. Change it here through pull requests, and keep it
+out of synchronization candidates and conflict resolution.
+
+This file is for repository contributors and is not part of the npm package (`files` only includes
+`dist`, `src`, `README.md` and `CHANGELOG.md`). Repository-wide rules are in the root
+[CONTRIBUTING.md](../../CONTRIBUTING.md) and [AGENTS.md](../../AGENTS.md); releases follow
+[RELEASING.md](RELEASING.md).
+
+## Commands
+
+```bash
+pnpm install --frozen-lockfile
+pnpm test:code-sdk          # Vitest suite "code-sdk" from test/vitest-suites.json
+pnpm typecheck:code-sdk     # SDK sources and tests
+pnpm --filter @minimax-ai/code-sdk run build
+```
+
+Both gates are part of `pnpm verify` on Linux and macOS, in the full and the platform profile. The
+Windows contract profile does not run them. Add new test files to the `code-sdk` group in `test/vitest-suites.json`.
+
+## Test doubles and contracts
+
+- The tests use `test/fixtures/cli-package/mcode.mjs` as a fake CLI. It replays recorded and
+  sanitized `stream-json` output from `test/fixtures/*.jsonl` (a successful run with tool calls, an
+  upstream failure, a resumed Session and a cancellation). Mock runs are not evidence of live model
+  behavior.
+- The same directory is linked as the `@minimax-ai/code` devDependency. pnpm installs a workspace
+  project's own peer dependencies, optional ones included; the link keeps the real CLI out of the
+  workspace and lets the tests exercise the "installed package" resolution path.
+- The SDK owns its public types (`src/types.ts`). `test/cli-contract.test.ts` imports the CLI's real
+  JSONL projector (`packages/tui/src/headless/events.ts`) and exit-code policy
+  (`packages/tui/src/headless/exit-policy.ts`) to check parsing, normalization and exit-code mapping.
+  `test/cli-resolution.test.ts` keeps `engines.node` identical to `packages/tui/package.json`. When
+  you change those CLI files or the CLI Node.js range, run the SDK suite as well.
+
+## Published text
+
+`dist/`, `src/`, `README.md` and `CHANGELOG.md` are published verbatim. Keep repository paths,
+CI job names and contributor instructions out of them; put them here or in `RELEASING.md`.
+`release:check` scans the packed tarball before every release. Its side-effect-free helpers
+(registry pinning and tool invocation) live in `scripts/release-tools.mjs` and are unit tested in
+`test/release-check.test.ts`.

packages/code-sdk/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MiniMax Code
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.