0fc0ae380b
* feat(agent-core): announce image compression and keep originals readable Every image ingestion point (ReadMediaFile, MCP tool results, clipboard paste, REST upload/inline base64, ACP) now places a <system> caption next to a compressed image stating the original vs. delivered dimensions, byte size, and format, so downsampling is never silent to the model. Originals stay readable: file uploads point at the stored blob, and in-memory images are persisted into the session's media-originals dir (content-addressed, size-capped, removed with the session; temp-dir fallback when no session is known). ReadMediaFile gains region (crop in original-image pixel coordinates, delivered at full fidelity) and full_resolution (skip downscaling, with an explicit error over the per-image byte limit), so the model can zoom into fine detail instead of silently degrading on large images. * fix(agent-core): exempt compression captions from the MCP text budget The caption announcing an image's compression was inserted before the shared 100K text budget was applied, so a chatty MCP result (page text + screenshot) consumed the budget first and the caption was evicted — or sliced mid-string into an unclosed <system> fragment — while the downsampled image survived, silently reintroducing the exact degradation the caption exists to report, and orphaning the persisted original. Split the size-limit pass in two and reorder the pipeline: the text budget now runs on the tool's own text BEFORE compression inserts captions (exempt by construction), and the per-part binary cap still runs after compression so compressible screenshots are kept. * fix(agent-core): harden crop error reporting and document readback semantics - cropImageForModel rejects non-finite region coordinates with a clean message instead of surfacing the codec's internal validation dump - the full_resolution and cropped-region over-budget errors now include exact byte counts alongside the rounded sizes, so a file a hair over budget no longer reads "is 3.8 MB, over the 3.8 MB limit" - read-media.md notes that re-reading a file without region or full_resolution reproduces the same downsampled image |
||
|---|---|---|
| .. | ||
| announce-image-compression-readback.md | ||
| cap-foreground-command-output.md | ||
| cli-narrow-terminal-crash.md | ||
| composer-send-arrow.md | ||
| config.json | ||
| fix-search-sessions-horizontal-scroll.md | ||
| moonshot-tool-call-id-recovery.md | ||
| pi-tui-history-filter.md | ||
| pi-tui-narrow-width-crash.md | ||
| prompt-accuracy-pass.md | ||
| README.md | ||
| refresh-web-icons.md | ||
| sharpen-compaction-handoff-prompt.md | ||
| shell-input-history.md | ||
Changesets
This repository uses changesets to manage npm package versions and releases.
Package Publishing Strategy
This repository uses an independent, manually-selected publishing strategy. When generating a changeset, only select the publishable packages that this change actually affects. The repository's .changeset/config.json already filters out internal workspace packages via ignore, so only the publishable packages listed below should appear in the pnpm changeset prompt.
Current publishable packages:
| Package | Directory | Description |
|---|---|---|
@moonshot-ai/kimi-code |
apps/kimi-code |
CLI / TUI application — provides the kimi command after install |
@moonshot-ai/kimi-code-sdk |
packages/node-sdk |
Public TypeScript SDK |
All other workspace packages are private internal packages, are not published to npm, and are excluded via ignore in .changeset/config.json:
@moonshot-ai/acp-adapter@moonshot-ai/agent-core@moonshot-ai/kaos@moonshot-ai/kimi-code-oauth@moonshot-ai/kimi-telemetry@moonshot-ai/kimi-web@moonshot-ai/kosong@moonshot-ai/migration-legacy@moonshot-ai/protocol@moonshot-ai/server@moonshot-ai/server-e2e@moonshot-ai/vis@moonshot-ai/vis-server@moonshot-ai/vis-webkimi-migration-legacy
Version impact from internal dependencies must be judged manually. The published artifacts for CLI and SDK bundle internal workspace packages into the artifact itself; runtime dependencies of published packages must not include any @moonshot-ai/* internal workspace packages.
The repository's .changeset/config.json sets updateInternalDependencies: "patch". Because internal packages are not published, you still need to manually select all affected publishable packages in the changeset — do not rely solely on automatic dependency bumps to express user-visible changes.
Example scenarios:
| Change | Changeset selection |
|---|---|
Only modifies TUI behavior in @moonshot-ai/kimi-code |
Add patch / minor / major to @moonshot-ai/kimi-code |
| Only modifies internal packages, no user-visible change in SDK / CLI | Usually no changeset needed |
| Internal package fix changes the CLI user experience | Add a changeset to @moonshot-ai/kimi-code describing the user-visible fix |
| Internal package adds a new capability exposed by the SDK | Add a changeset to @moonshot-ai/kimi-code-sdk |
| SDK behavior change affects CLI user experience | Add changesets to both @moonshot-ai/kimi-code-sdk and @moonshot-ai/kimi-code |
| Provider abstraction change affects SDK / CLI | Add changesets to the affected @moonshot-ai/kimi-code-sdk and/or @moonshot-ai/kimi-code |
| Test-only, internal refactor, docs, or private debug tooling changes | Usually no changeset needed |
Bundled official plugin change under plugins/ (e.g. kimi-datasource) |
No changeset — the plugin is versioned via its own kimi.plugin.json / plugins/marketplace.json and shipped through the marketplace CDN, not the npm package |
Prerequisite: NPM Trusted Publishing (OIDC)
This repository uses npm's Trusted Publishing (OIDC-based) for publishing — no NPM_TOKEN is required.
Configuration steps
- Open each publishable package's page on the npm website, e.g.
https://www.npmjs.com/package/@moonshot-ai/kimi-code. - Go to Settings -> Publishing access.
- Find Automate publishing with GitHub Actions or Add trusted publisher.
- Click Add a new trusted publisher.
Fill in the following:
| Field | Value |
|---|---|
| GitHub Organization | MoonshotAI |
| GitHub Repository | kimi-code |
| GitHub Workflow | release.yml |
| Environment | leave empty |
Each publishable package needs its Trusted Publisher configured once. The current GitHub Actions workflow lives at .github/workflows/release.yml and already has id-token: write configured.
Development Workflow
1. Implement the feature or fix
Complete code, tests, and documentation changes as usual. A changeset is required when the change affects user-visible behavior, public API, dependency ranges, or release artifacts of a publishable package.
2. Generate a changeset
From the repository root:
pnpm changeset
Follow the prompts to choose:
- Which publishable packages this change affects;
- The version bump level:
patch: bug fixes, small changes, follow-up dependency updates;minor: backward-compatible new features;major: breaking changes;
- A user-facing description of the change.
The command creates a .changeset/*.md file that must be committed alongside the code.
3. Commit the changeset
git add .changeset/
git commit -m "chore: add changeset for package release"
git push
Commit messages must follow Conventional Commit style. Do not include any author/agent identity in the commit message.
4. CI generates the release PR
Once the changeset file is merged into main, .github/workflows/release.yml uses changesets/action@v1 to create or update a release PR.
The release PR runs:
pnpm changeset version: bumps publishable package versions and updates changelogs;- Deletes the consumed
.changeset/*.mdfiles; - Uses the title
[CI]: Release packages.
5. Merge the release PR
Once the release PR is merged into main, the same workflow runs:
pnpm install --frozen-lockfilepnpm buildpnpm changeset publish
The packages are then published via npm Trusted Publishing, and a GitHub Release is created.
Manual Publishing (Not Recommended)
Only publish manually when CI is unavailable. Before publishing manually, make sure you are logged into npm locally and using the Node.js and pnpm versions required by the repository.
pnpm run version
pnpm run publish
The underlying changesets commands are:
pnpm changeset version
pnpm changeset publish
The root-level pnpm run publish first runs typecheck, lint, sherif, test, build, and package lint, then runs changeset publish.
Notes
- Every PR that affects publishable-package behavior or public API should include a corresponding changeset.
- Changes under
plugins/(the bundled official plugins such askimi-datasource) do not need a changeset: each plugin carries its own version inkimi.plugin.jsonandplugins/marketplace.jsonand is distributed via the marketplace CDN, separately from the@moonshot-ai/kimi-codenpm package. - Changeset files must be committed to the repository — release PRs are only triggered after they're merged.
- Release PRs require human review and merge; they will not publish automatically.
- Do not add release changesets for private internal packages; only select
@moonshot-ai/kimi-codeand@moonshot-ai/kimi-code-sdk. - If a change in an underlying internal package alters user-visible behavior or public API of a publishable package, add a changeset to the affected publishable package. For example, when a bug fixed in
@moonshot-ai/agent-coreresolves an issue CLI users encounter, add a changeset to@moonshot-ai/kimi-codedescribing the user-visible fix. @moonshot-ai/kimi-codeis the official CLI package name; after a global install it provides thekimicommand.- Make sure each publishable package on npm has a Trusted Publisher configured.