[hetaoBackend]

Thanks for your interest in contributing. For now, code and documentation pull requests are accepted only from repository collaborators. If you are not a collaborator, please open an issue so we can discuss your idea.

Change

Adds @minimax-ai/code-sdk (packages/code-sdk), a zero-dependency TypeScript SDK for driving the local MiniMax Code agent from Node.js. It is similar to the Codex TypeScript SDK. The SDK wraps the existing mcode exec --output-format stream-json contract and does not add a new execution protocol.

• Execution model. Each thread.run() / thread.runStreamed() starts one mcode exec process, which runs one Turn. The prompt is written to stdin as {"prompt": ...}. A Thread only holds the Session id and continues it with --session.

• API.

  • new MCode({ bin, dataDir, env, configPath }), startThread, resumeThread, run, runStreamed and thread.id.
  • run() resolves only on succeeded. runStreamed() delivers turn.failed as an ordinary event.
  • A concurrent Turn on the same Thread throws ThreadBusyError.
  • dataDir maps to MINIMAX_DATA_DIR.

• CLI resolution. In order:

  1. the explicit bin option;
  2. an installed @minimax-ai/code;
  3. the nearest node_modules/.bin/mcode above the working directory, so any project-local CLI distribution works;
  4. mcode on PATH.

  On Windows, the official installer's versioned mcode.cmd and npm/pnpm .cmd / .ps1 shims are followed to their JS entry; the SDK never starts the CLI through a shell. The SDK runs a cached mcode --version check (minimum 0.7.0) and accepts only events with schemaVersion === 1.

• Results and errors.

  • Items are merged by id. Identical repeated snapshots are dropped, and unfinished items are marked incomplete.
  • Errors are typed and mapped from the exec status and the exit codes 0/2/3/4/6/7/70/130/141.
  • Failures carry the observed sessionId.

• Process handling.

  • AbortSignal sends SIGINT, then SIGTERM after 10s, then SIGKILL after another 5s.
  • timeoutMs maps to --timeout <n>ms. The SDK force-stops the CLI at timeoutMs + 30s, with a validated upper bound.
  • After exit, the SDK drains stdout/stderr for at most 2s, so grandchildren holding the pipes cannot stall a Turn.
  • Temporary prompt files are removed before a run settles.
  • Running CLI processes are cleaned up on a normal host exit.

• Publication metadata.

  • Version 0.1.0, MIT, not private.
  • publishConfig pins https://registry.npmjs.org/ with public access. All release commands also pin --@minimax-ai:registry, because a scoped registry setting overrides publishConfig.
  • Published files: dist, src, README.md, CHANGELOG.md (npm adds package.json and LICENSE).
  • engines.node equals the CLI's >=22.19 <23 || >=24.2 <27, and a test enforces this.
  • @minimax-ai/code >=0.7.0 is an optional peer dependency.

• Manual release support. packages/code-sdk/RELEASING.md documents the steps. pnpm --filter @minimax-ai/code-sdk run release:check:

  • checks for a clean, up-to-date main;
  • checks that the version matches the first CHANGELOG section and is not yet on npm;
  • builds, type-checks and tests;
  • runs npm pack, applies a tarball entry allowlist and scans every packed file for internal hosts, credentials, local user paths, other repository package paths and internal package names;
  • runs an import/require smoke test from the tarball;
  • prints, but does not run, the npm publish and read-back commands.

  --allow-non-main rehearses on a feature branch without printing a publish command.

• Repository integration.

  • The package is added to pnpm-workspace.yaml and to release/extraction.json packageRoots.
  • pnpm gen:tsconfig was run.
  • The test files form a new code-sdk group in test/vitest-suites.json.
  • scripts/verify.mjs gains typecheck:code-sdk and test:code-sdk. Both are Linux/macOS only, outside the Windows contract.
  • The check:source internal-text and credential patterns move unchanged to scripts/lib/public-text-policy.mjs, so release:check reuses them.
  • The lockfile only gains the new importer.
  • README.md / README_ZH.md gain one entry-point row each.

The tests replay recorded, sanitized stream-json output through a fake mcode. test/cli-contract.test.ts imports the CLI's real JSONL projector (packages/tui/src/headless/events.ts) and exit-code policy, so changes on either side surface in the SDK suite.

• PR labels: enhancement, cli.

Validation

• Checks run and results (local runs on revision 701cb82, macOS arm64, pnpm 9.12.0; the follow-up f441c7d was re-checked as noted below):
  • pnpm verify (full profile) on the committed, clean tree with official Node v24.22.1: passed, 17 gates, including the new typecheck:code-sdk and test:code-sdk. Skipped: test:windows (not applicable on macOS) and test:release-package (requires an npm release archive).
  • The same run with Homebrew Node v26.4.0 failed one existing TUI test unrelated to this change: update-runtime.test.ts, "heals receipts pinned to a Homebrew Cellar keg via the stable opt path". The test copies the current node binary into a fake Cellar, and Homebrew's Node dynamically links libnode.147.dylib, so the copy aborts (dyld: Library not loaded). It fails the same way when run alone, and this PR does not touch packages/tui.
  • pnpm test:code-sdk: 7 files, 60 tests passed. pnpm typecheck:code-sdk and pnpm --filter @minimax-ai/code-sdk run build passed.
  • pnpm check:source, pnpm check:tsconfig and pnpm test:release-tools (54 passed, 1 platform skip) passed.
  • ESLint with the repository rules on packages/code-sdk: 0 errors. The SDK is not part of the lint:tui gate.
  • pnpm --filter @minimax-ai/code-sdk run release:check -- --allow-non-main:
    • the tarball has 64 files, all inside the allowlist, with no private-text findings;
    • the import/require smoke test from the tarball passed;
    • @minimax-ai/[email protected] is confirmed absent from npmjs;
    • nothing was published.
  • Negative checks: a dirty tree makes release:check fail, and the scan rules flag sample other-package paths, /Users/… and C:\Users\… paths, and internal package names.
• f441c7d addresses the CodeQL alerts raised on the first push (1 high: polynomial regex in the Windows argument quoting; 4 medium: shell command construction). It removes the cmd.exe fallback and its quoting entirely. After it: pnpm test:code-sdk (60 passed), pnpm typecheck:code-sdk, pnpm check:source, ESLint (0 errors). GitHub Checks on f441c7d: all passed, including CodeQL, verify on ubuntu/macos/windows with Node 24, install on Node 22.19.0/24.2.0/25/26 for ubuntu and macOS, verification and source-history-artifact.
• Local end-to-end validation with live models (packed tarball of 46f8dbe, installed into fresh projects under a temporary directory and used through import '@minimax-ai/code-sdk'; macOS arm64, Node v26.4.0, npm 11.17.0; model minimax/MiniMax-M3.1-Flash; CLI: a local MCode CLI 0.7.0 preview build on PATH, and @minimax-ai/[email protected] from npm installed into the project). All of the following passed:
  • run() with tool calls, files and appendSystemPrompt: the agent read a file, listed the workspace, wrote out.txt (HELLO SDK) and answered from the attached log; items, usage and model were populated; thread.id was null before the first run and equal to the result's sessionId after it.
  • resumeThread(): same sessionId, context kept (the agent recalled the earlier file content without tools).
  • runStreamed(): the stream starts with exec.started and ends with exec.completed, sequence is strictly increasing, and the result status is succeeded.
  • A second run() on a busy Thread throws ThreadBusyError.
  • Cancelling run() during a long shell command throws MCodeAbortError (name === 'AbortError', exit 130, result.status === 'cancelled', sessionId set). Cancelling runStreamed() ends the stream in about 2.4 s with turn.failed (cancelled) and exec.completed (cancelled), as documented. No sleep or mcode exec processes were left behind in either case.
  • timeoutMs: 15000 around a 45 s shell command: MCodeRunError with status === 'timeout' and sessionId set, no leftover processes.
  • Error mapping without model calls: a missing bin gives MCodeNotFoundError; an invalid effort gives MCodeInvocationError (exit 2, with the CLI's list of levels); an empty dataDir gives MCodeRunError with category === 'config' (exit 3, sign-in prompt).
  • A wrapper bin that logs its argv confirmed the SDK passes --append-system-prompt-file=<file> with mode 600 and the exact text, and removes the temporary directory after the run.
  • Resolution of a project-local @minimax-ai/[email protected] with PATH restricted to system directories: a full Turn succeeded (out.txt written). A control project without the CLI fails with MCodeNotFoundError under the same PATH.
  • Found during this run and fixed in 2179002: npm 11 rejects --allow-scripts for project-scoped installs (EALLOWSCRIPTS); the README now documents the allowScripts entries required in the project's package.json.
  • Observed, not an SDK defect: the hosted models did not follow an appended system prompt rule (ending the answer with a marker). Passing the same text with the CLI's own --append-system-prompt behaves the same, and the SDK passes it through correctly (see the argv log above).
• Performance: basic. The change adds a separate package and does not touch the CLI runtime paths covered by perf:full.
• NOT RUN, platform limitations and live-service boundaries:
  • Windows: not run. Cancellation on Windows is a hard kill (documented). Windows shim resolution is covered only by pure-function tests. test:code-sdk is excluded from the Windows contract.
  • Live models: the offline tests and fixtures are not live-model acceptance; the live-model runs above cover one model on macOS only.
  • Not published to npm. The first publication follows RELEASING.md manually. @minimax-ai/[email protected] from npm was exercised for one Turn (above); 0.7.0 is accepted by the argument check but was not run with a model.
  • The host-exit cleanup path has no automated test.

Publication and contribution checks

• I have permission to contribute these changes under the existing licenses applicable to the changed files/packages; imported material and its provenance are identified and existing notices are preserved.
• No credentials, account data, real user content, internal source history or private review material is included.
• Added/removed source files were reviewed before regenerating release/public-source.json; new tests are declared in test/vitest-suites.json where applicable.
• Shared English/Chinese documentation and capability/verification records are updated where applicable. Mock/offline results are not described as live-service acceptance.

Maintainer handoff

Publication scope or license changes (if any):

• New MIT package packages/code-sdk (37 files), intended for npm as @minimax-ai/code-sdk.
• The recorded CLI fixtures were sanitized: account and organization identifiers, provider ids, local paths and user names were removed.
• scripts/lib/public-text-policy.mjs holds the existing check:source patterns.

Shared-source port: not applicable. This is a public-only package: this repository is its single source, and source synchronization does not produce or update it (stated in packages/code-sdk/CONTRIBUTING.md).

Review fixes

Each item was reproduced first; the evidence is "before → after".

• B1 — scoped registry overrode the publish target. A user npmrc with @minimax-ai:registry=<mirror> beat both publishConfig.registry and --registry. The npm lookup in release:check and the RELEASING read-back would then query the same wrong registry.
  • Fix: release:check first reads the effective @minimax-ai:registry and default registry, and fails with a fix-it hint if the scope points anywhere but npmjs. Every npm command it runs or prints, and every command in RELEASING.md (publish, view, dist-tags, install smoke, deprecate), passes both --registry=https://registry.npmjs.org/ and --@minimax-ai:registry=https://registry.npmjs.org/. RELEASING now says publishConfig only replaces the default registry.
  • Evidence: with an isolated userconfig, npm publish --dry-run --registry=npmjs went from Publishing to http://127.0.0.1:9/scoped/ to Publishing to https://registry.npmjs.org/ once the printed command was used. release:check now stops at "npm registry configuration" with @minimax-ai:registry is set to http://127.0.0.1:9/scoped/ ….
  • Regression test: test/release-check.test.ts runs the script with an isolated userconfig (no network access, no publication) and unit-tests the pinned flags.
• N1 — official Windows installer layout. The installer's root mcode.cmd (SET /P MCODE_RELEASE=<"%~dp0current" + CALL "%~dp0releases\%MCODE_RELEASE%\.mcode-launcher.cmd", the same text packages/tui/src/update/versioned-prefix.ts writes) failed with MCodeNotFoundError.
  • Fix: the SDK follows current, validates the release key with the launcher's own rule, and parses .mcode-launcher.cmd to the JS entry. It still runs that entry with process.execPath, no shell. The pointer is re-read before every spawn, so a self-update between Turns is used.
  • Errors: no more mcode.exe; an installed but unfollowable launcher asks for bin instead of suggesting npm install.
  • Evidence: the review's simulated install went from MCodeNotFoundError … (or mcode.exe) … Install it with npm … to { kind: 'node', path: …\releases\0.7.1\…\cli.js, launcher: …\mcode.cmd }.
  • Tests: three new tests (platform: 'win32' on a generated layout), covering resolution via PATH and bin, re-resolution after current changes, and the error text. The README lists the supported Windows installations.
• N2 — unnecessary check:source exemption. Removed.
  • Evidence: appending an internal URL to scripts/lib/public-text-policy.mjs went from "check passed" to scripts/lib/public-text-policy.mjs: internal source reference.
  • Regression test added in test/source-sync.test.mjs.
• N3 — error table. The README now maps exec.completed results and exits without a result separately. Only exit 0 without a result is a protocol error; any other unknown exit code (for example 1) or a signal becomes an internal MCodeRunError. A test for exit 1 was added.
• N5 — Windows shell in release:check. No tool is started through a shell any more. Node.js runs directly; on Windows, npm and pnpm run through their JS entries, and missing entries fail with a clear message. Unit tests cover the Windows invocation; it has not been run on a Windows machine.
• N7. CONTRIBUTING.md states that this repository is the package's single source and that it is not produced by source synchronization.
• Nits.
  • The minimum-version comment now records the public 0.7.0 verification.
  • CONTRIBUTING: both SDK gates run in the full and platform profiles.
  • README: describes require(esm) support instead of a CommonJS export condition.

Commits: d2506b3 (B1/N5), fe912d2 (N1), 616ac3c (N2), 46f8dbe (N3/N7/nits).

Checks on 46f8dbe:

• pnpm test:code-sdk: 8 files, 69 tests.
• pnpm typecheck:code-sdk, the package build, pnpm check:source and pnpm check:tsconfig: passed.
• node --test test/source-sync.test.mjs: 55 passed, 1 platform skip.
• ESLint on packages/code-sdk: 0 errors.
• release:check -- --allow-non-main: passed; 64 files, no findings; ends with the rehearsal warning.
• Full pnpm verify: passed, 17 gates, on official Node v24.22.1 (macOS arm64). Skipped: test:windows (not applicable) and test:release-package (needs an npm release archive).

Review (yujiachen-y) — 2b865af, 552c815

Addressed the second review pass on 2179002. Decision and fixes:

• CLI resolution (maintainer decision). Chose option 1 (opt-in). resolveFromCwd defaults to false. Default order: explicit bin → @minimax-ai/code next to the SDK → mcode on PATH. With resolveFromCwd: true, cwd package.json / parent walk for node_modules/.bin/mcode runs before PATH. Untrusted-cwd risk documented in the README.
• EMFILE / spawn error. Attach the 'error' listener immediately after spawn, before reading stdio, so spawn failures become typed SDK errors instead of crashing the host.
• Ctrl+C / process group. CLI stays in the host process group (intentional). Cancel sends SIGTERM then SIGKILL after 60s; the SDK no longer sends SIGINT, so it does not collide with Ctrl+C consuming the CLI's one-shot handler. A second SIGINT (double Ctrl+C) can still kill the CLI before exec.completed — documented caveat.
• Kill windows. Cancel: SIGTERM → SIGKILL after 60s. Timeout backstop: timeoutMs + 90s (60s shutdown + 30s startup slack). After exec.completed, lingering CLI is SIGKILLed after 5s.
• MIN_CLI_VERSION. Set to 0.6.3; optional peer @minimax-ai/code >=0.6.3 so this repo's 0.6.5 CLI is accepted.
• Contract test. Extended to parse argv and stdin via the CLI's applyExecCliContract / resolveTuiExecInvocation.
• Local-path scan. Covers /Users/, /home/<name>/, /root/, /private/var/folders/, C:\Users\, and escaped C:\\Users\\.
• Publish guard. prepublishOnly runs node scripts/release-tools.mjs, which always exits 1 from the package directory.
• Temp prompt dirs. exit hook uses sync rmSync so mid-turn process.exit() still cleans $TMPDIR/mcode-sdk-*.
• Release regression tests. Allowlist / path rules / rehearsal live in scripts/release-tools.mjs, covered by test/release-check.test.ts.
• 552c815. Keeps published comments free of other package paths.

Local verification on Linux (Node 24.22.2, pnpm 9.12.0, mcode 0.6.5, model MiniMax-M3) at 552c815: full pnpm verify (16 gates; Windows/sandbox skipped on Linux), 81 code-sdk tests, and live-model e2e for run / resumeThread, AbortSignal cancel, timeoutMs, resolveFromCwd on/off, mid-turn process.exit temp cleanup, and npm publish --dry-run blocked by prepublishOnly.

Follow-ups (not in this PR)

• N4: a Windows automated subset of the SDK tests.
• N6: the CLI silently falling back to the default model for an unknown model id (separate CLI PR).
• npm --provenance for SDK releases.

[yujiachen-y]

AI-assisted review (trial of a new review flow): needs maintainer decision

0 blocking · 1 needs a maintainer decision · 9 suggestions (P2, non-blocking), all posted as inline comments. Reviewed at 2179002, including the five commits pushed after f441c7d. Points the PR now declares (public-only single source, provenance as a follow-up) are not raised again.

Scope	da22f11c..2179002d, new package packages/code-sdk plus repository wiring
Tier	Large: touches release tooling, CI gates and child-process handling
Method	Four parallel review passes (security and supply chain, CLI contract, process lifecycle, repository integration and release) plus a full read; the five later commits were reviewed as an increment. Every candidate was re-checked in a separate context that tried to refute it: 1 was refuted and 4 were downgraded.
Limits	Static review. Five findings were reproduced with probes that load the SDK sources in memory or run the test fixtures. vitest, tsc and a live CLI were not run here, and Windows was not tested.

Needs a maintainer decision. .github/CODEOWNERS lists only the author, and docs/maintainers.md asks for a non-author approval, so this is for the reviewer the release coordinator assigns; the author does not need to answer it.

• CLI resolution can execute an mcode from the host's current directory or a parent directory (src/cli-resolver.ts).

Suggestions (P2). Spawn failure such as EMFILE crashes the host · Ctrl+C in a terminal can kill the CLI before it finishes cancelling · kill windows are shorter than the CLI's shutdown budget · the minimum CLI version rejects the CLI built from this repository · the contract test does not cover argv or stdin · the release scan misses common local-path forms · first non-private workspace package without a publish guard · temporary system-prompt files left behind on process.exit() · no regression tests for the text scan and allowlist.

Claims from the PR description that do not fully hold

• "Failures carry the observed sessionId": MCodeProtocolError and MCodeVersionError do not (packages/code-sdk/src/errors.ts:103-108, packages/code-sdk/src/errors.ts:127-135); thread.id is still available.
• "Both are Linux/macOS only": typecheck:code-sdk has no platforms, so on Windows it runs in the full, platform and archive profiles. CI uses the windows profile there, so CI is not affected (scripts/verify.mjs:59-63).
• "changes on either side surface in the SDK suite": true for the projector and exit codes, not for argv and stdin (see the contract-test comment).
• release:check checks for an "up-to-date main": it compares with the local origin/main and does not fetch (packages/code-sdk/scripts/release-check.mjs:138-142).

Other observations (no separate comment)

• .agents/skills/testing-workflow/SKILL.md does not list the new gates, although CONTRIBUTING.md asks to update the relevant skill; pnpm verify still runs them.
• checkCliVersion waits only for 'close' (packages/code-sdk/src/version.ts:94-106), so a wrapper that leaves a descendant holding the pipes would hang it. The official --version path starts no child processes.
• release:check --offline on main still prints the publish command (packages/code-sdk/scripts/release-check.mjs:172-174).
• Checked and not an issue: runtime startup redirects console to the log file, so migration log lines do not reach the stream-json stdout.

[hetaoBackend]

@yujiachen-y 你提的几点都改完并回复了（cwd 走了 opt-in），本地也跑过全量 pnpm verify 和真实模型的取消 / 超时 / resolveFromCwd 路径。方便的话再帮看一眼？

[yujiachen-y]

AI-assisted review, round 2: pass

Re-reviewed at 552c815, covering the increment since 2179002 (2b865af, 552c815). All 10 points from round 1 are addressed; each thread has a short verification note and is resolved. No new issues were found in the increment, and all 21 checks pass.

Extra checks beyond reading the diff:

• npm 11.13: prepublishOnly runs for npm publish in the package directory and does not run for npm publish <tarball>, so the guard blocks only the unintended path.
• The CLI keeps a once('SIGTERM') listener until runExec returns (packages/tui/src/cli/run-exec-command.ts:52, removed at :128), so the SDK's SIGTERM cancel is still handled as a cancel after a terminal Ctrl+C.
• LOCAL_USER_PATH: all six target path forms match; nearby forms such as /homework/ do not.

Optional, non-blocking:

• test/cli-contract.test.ts is still excluded from tsconfig.check.json.
• The shared credential pattern does not match npm tokens, JWTs or AWS keys (tracked sources are covered by gitleaks).
• Unchanged notes from round 1: .agents/skills/testing-workflow/SKILL.md does not list the new gates, and release:check --offline on main still prints the publish command.

Limits: static review plus the probes above; the SDK test suite was not run locally.

[yujiachen-y]

Approving after verifying the round-2 fixes. Thanks for the quick turnaround.