@pheem49/mint 1.15.0 → 1.17.0

package/crates/mint-mod-runtime/src/test_sdk.js

@@ -0,0 +1,32 @@
+const __tests = [];
+function __test(name, run, fixtures = {}) {
+  if (typeof name !== 'string' || !name || name.length > 120 || typeof run !== 'function' || __tests.length >= 64 || __tests.some(t => t.name === name)) throw Error('Invalid or duplicate test');
+  __tests.push({name, run, fixtures: JSON.parse(JSON.stringify(fixtures))});
+}
+function __normal(value) {
+  if (value == null) return null;
+  if (Array.isArray(value)) return value.map(__normal);
+  if (typeof value === 'object') return Object.fromEntries(Object.keys(value).sort().map(k => [k, __normal(value[k])]));
+  return value;
+}
+async function __runTest(index) {
+  function checkSnapshot() {
+    const response=JSON.parse(__host(JSON.stringify({kind:'test_snapshot', value:__view})));
+    if (response.error) throw Error(response.error);
+  }
+  const context = Object.freeze({
+    mint,
+    async emit(kind, payload = {}) {
+      if (!__events.includes(kind)) throw Error('Invalid test event');
+      if (['usage_update','context_compacted','turn_end'].includes(kind)) __host(JSON.stringify({kind:'test_usage', value:payload}));
+      const result=await __dispatch(kind, payload); checkSnapshot(); return result;
+    },
+    async command(name, value) { const result=await __dispatch('action', {action:name, value}); checkSnapshot(); return result; },
+    ui(slot) { return JSON.parse(JSON.stringify(__view.ui[slot] ?? null)); },
+    state(key) { return JSON.parse(JSON.stringify(__view.state[key] ?? null)); },
+    equal(actual, expected, message = 'Values differ') {
+      if (JSON.stringify(__normal(actual)) !== JSON.stringify(__normal(expected))) throw Error(`${message}: expected ${JSON.stringify(expected)}, received ${JSON.stringify(actual)}`);
+    }
+  });
+  await __tests[index].run(context);
+}

package/crates/mint-mod-runtime/src/testing.rs

@@ -0,0 +1,94 @@
+use super::*;
+use std::sync::Mutex;
+
+impl Engine {
+    fn load_tests(&self, compiled: &str) -> Result<Vec<Value>, String> {
+        *self.deadline.lock().unwrap() = cpu_time::ThreadTime::now().as_duration();
+        let metadata = self
+            .context
+            .with(|ctx| -> rquickjs::Result<String> {
+                ctx.eval::<(), _>(include_str!("test_sdk.js"))?;
+                let module = Module::declare(ctx.clone(), "tests", compiled)?;
+                let (module, promise) = module.eval()?;
+                promise.finish::<()>()?;
+                let register: Function = module.get("registerTests")?;
+                let test: Function = ctx.eval("__test")?;
+                let returned: rquickjs::Value = register.call((test,))?;
+                if let Some(promise) = returned.as_promise() {
+                    promise.clone().finish::<()>()?;
+                }
+                ctx.eval("JSON.stringify(__tests.map(t=>({name:t.name,fixtures:t.fixtures})))")
+            })
+            .map_err(|e| self.error(e))?;
+        serde_json::from_str(&metadata).map_err(|e| e.to_string())
+    }
+    fn run_test(&self, index: usize) -> Result<(), String> {
+        *self.deadline.lock().unwrap() = cpu_time::ThreadTime::now().as_duration();
+        self.context
+            .with(|ctx| -> rquickjs::Result<()> {
+                let promise: Promise = ctx.eval(format!("__runTest({index})"))?;
+                promise.finish::<()>()
+            })
+            .map_err(|e| self.error(e))?;
+        self.snapshot()?;
+        Ok(())
+    }
+}
+pub fn run_tests(manifest: &Value, source: &str, files: &[(&str, &str)]) -> Result<Value, String> {
+    if files.is_empty() || files.len() > 32 {
+        return Err("Provide 1–32 .test.ts/.test.js files".into());
+    }
+    let manifest: Manifest = serde_json::from_value(manifest.clone()).map_err(|e| e.to_string())?;
+    let compiled = compile(&manifest, source)?;
+    let mut results = vec![];
+    for (filename, test_source) in files {
+        let test_code = compile(&manifest, test_source)?;
+        let registry = Engine::new("export function register(){}", &json!({}), |_| {
+            json!({"error":"No host access while registering tests"}).to_string()
+        })?;
+        let tests = registry.load_tests(&test_code)?;
+        if tests.is_empty() {
+            return Err(format!("No tests registered in {filename}"));
+        }
+        for (index, test) in tests.iter().enumerate() {
+            let fixtures = test["fixtures"].clone();
+            let usage = Arc::new(Mutex::new(
+                fixtures
+                    .get("usage")
+                    .cloned()
+                    .unwrap_or_else(unavailable_usage),
+            ));
+            let current = usage.clone();
+            let permissions = manifest.permissions.clone();
+            let result = (|| -> Result<(), String> {
+                let engine = Engine::new(
+                    &compiled,
+                    &fixtures.get("state").cloned().unwrap_or_else(|| json!({})),
+                    move |request| {
+                        let request: Value = serde_json::from_str(&request).unwrap_or_default();
+                        match request["kind"].as_str() {
+                        Some("usage")=>json!({"value":current.lock().unwrap().clone()}),
+                        Some("viewport")=>json!({"value":fixtures.get("viewport").cloned().unwrap_or_else(unavailable_viewport)}),
+                        Some("test_usage")=>{*current.lock().unwrap()=request["value"].clone();json!({"value":null})},
+                        Some("test_snapshot")=>match validate_snapshot(&request["value"]){Ok(())=>json!({"value":null}),Err(error)=>json!({"error":error})},
+                        Some("read") if permissions.iter().any(|p|p=="workspace.read")=>{
+                            match request["path"].as_str().and_then(|path|fixtures["files"].get(path)).filter(|v|v.is_string()) {
+                                Some(value)=>json!({"value":value}),None=>json!({"error":"No file fixture for this path"}),
+                            }
+                        }
+                        _=>json!({"error":"Test host capability unavailable; external tools and I/O are disabled"}),
+                    }.to_string()
+                    },
+                )?;
+                let registered = engine.load_tests(&test_code)?;
+                if registered.get(index).and_then(|t| t["name"].as_str()) != test["name"].as_str() {
+                    return Err("Test registration must be deterministic".into());
+                }
+                engine.run_test(index)
+            })();
+            results.push(json!({"file":filename,"name":test["name"],"passed":result.is_ok(),"error":result.err()}));
+        }
+    }
+    let passed = results.iter().filter(|t| t["passed"] == true).count();
+    Ok(json!({"passed":passed,"failed":results.len()-passed,"tests":results}))
+}

package/crates/mint-mod-runtime/tests/runtime.rs

@@ -0,0 +1,156 @@
+use mint_mod_runtime::{preview, validate_package};
+use serde_json::{Value, json};
+
+fn manifest() -> Value {
+    json!({"id":"meter","name":"Token meter","version":"1.0.0","sdkVersion":1,"entry":"main.ts","permissions":[]})
+}
+#[test]
+fn session_and_viewport_getters_work_before_the_first_event() {
+    let engine=mint_mod_runtime::Engine::new("export function register(mint){const u=mint.session.usage();const v=mint.ui.viewport();mint.ui.set('above_composer',{type:'text',text:u.context.tokens+' / '+v.columns});mint.on('ui_resize',()=>mint.log('resized'));}",&json!({}),|request| {
+        let request:Value=serde_json::from_str(&request).unwrap();
+        match request["kind"].as_str() { Some("usage")=>json!({"value":{"context":{"tokens":36100}}}).to_string(), Some("viewport")=>json!({"value":{"columns":80}}).to_string(), _=>panic!("Unexpected host request") }
+    }).expect("Basic getters require no filesystem/tool capabilities");
+    assert_eq!(
+        engine.snapshot().unwrap()["ui"]["above_composer"]["text"],
+        "36100 / 80"
+    );
+}
+#[test]
+fn preview_can_use_basic_getters_with_explicit_unavailable_values() {
+    let value=preview(&manifest(),"export function register(mint){mint.ui.set('above_composer',{type:'text',text:String(mint.session.usage().context.tokens)+' / '+String(mint.ui.viewport().columns)});}").unwrap();
+    assert_eq!(value["ui"]["above_composer"]["text"], "null / null");
+}
+#[test]
+fn mod_test_runner_uses_real_events_fixtures_and_isolates_cases() {
+    let source = "export function register(mint){mint.state.set('initial',mint.session.usage().context.tokens);mint.on('usage_update',e=>mint.ui.set('above_composer',{type:'text',text:String(e.context.tokens)}));}";
+    let test_source = r#"export function registerTests(test){
+        test('updates',async({emit,ui,equal,state})=>{equal(state('initial'),36100);await emit('usage_update',{context:{tokens:134400}});equal(ui('above_composer').text,'134400');},{usage:{context:{tokens:36100}}});
+        test('isolated',({ui,equal})=>equal(ui('above_composer'),null));
+        test('failure',({equal})=>equal(1,2,'intentional failure'));
+    }"#;
+    let result =
+        mint_mod_runtime::run_tests(&manifest(), source, &[("weather.test.ts", test_source)])
+            .unwrap();
+    assert_eq!(result["passed"], 2);
+    assert_eq!(result["failed"], 1);
+    assert!(
+        result["tests"][2]["error"]
+            .as_str()
+            .unwrap()
+            .contains("intentional failure")
+    );
+}
+#[test]
+fn mod_test_runner_interrupts_a_loop_and_reports_missing_tests() {
+    assert!(mint_mod_runtime::run_tests(&manifest(), "export function register(){}", &[]).is_err());
+    let result = mint_mod_runtime::run_tests(
+        &manifest(),
+        "export function register(){}",
+        &[(
+            "loop.test.ts",
+            "export function registerTests(test){test('loop',()=>{while(true){}});}",
+        )],
+    )
+    .unwrap();
+    assert_eq!(result["failed"], 1);
+}
+#[test]
+fn mod_test_runner_rejects_invalid_ui_at_each_dispatch() {
+    let source = "export function register(mint){mint.on('usage_update',()=>mint.ui.set('above_composer',{type:'html',html:'bad'}));mint.commands.register('repair',()=>mint.ui.set('above_composer',{type:'text',text:'Ready'}));}";
+    let result=mint_mod_runtime::run_tests(&manifest(),source,&[("ui.test.ts","export function registerTests(test){test('invalid update',async({emit,command})=>{await emit('usage_update',{});await command('repair');});}")]).unwrap();
+    assert_eq!(result["failed"], 1);
+}
+#[test]
+fn mods_can_subscribe_to_context_compaction() {
+    assert!(preview(&manifest(), "export function register(mint){mint.on('context_compacted', e => mint.log(e.contextStatus));}").is_ok());
+}
+#[test]
+fn ui_rejects_unbounded_colors_and_invalid_row_directions() {
+    assert!(preview(&manifest(), "export function register(mint){mint.ui.set('above_composer',{type:'text',text:'Weather',color:'url(evil)'});}").is_err());
+    assert!(preview(&manifest(), "export function register(mint){mint.ui.set('above_composer',{type:'stack',direction:'diagonal',children:[]});}").is_err());
+}
+#[test]
+fn weather_row_accepts_all_five_named_colors() {
+    for color in ["yellow", "cyan", "blue", "magenta", "red"] {
+        let source = format!(
+            "export function register(mint){{mint.ui.set('above_composer',{{type:'stack',direction:'row',children:[{{type:'text',text:'Weather',color:'{color}'}}]}});}}"
+        );
+        assert!(
+            preview(&manifest(), &source).is_ok(),
+            "{color} must be supported"
+        );
+    }
+}
+
+#[test]
+fn typescript_mod_registers_and_renders_without_node() {
+    let source = r#"export function register(mint: any) {
+      mint.ui.set('above_composer', {type:'text', text:'Usage unavailable'});
+      mint.on('usage_update', (event: any) => mint.ui.set('above_composer', {type:'text', text:String(event.totalTokens)}));
+    }"#;
+    let result = preview(&manifest(), source).expect("valid mod loads");
+    assert_eq!(result["ui"]["above_composer"]["text"], "Usage unavailable");
+}
+
+#[test]
+fn invalid_ids_and_external_imports_are_rejected() {
+    let mut m = manifest();
+    m["id"] = json!("../outside");
+    assert!(validate_package(&m, "export function register(mint) {}").is_err());
+    assert!(
+        validate_package(
+            &manifest(),
+            "import fs from 'node:fs'; export function register() {}"
+        )
+        .is_err()
+    );
+}
+
+#[test]
+fn infinite_loop_is_interrupted() {
+    let start = std::time::Instant::now();
+    assert!(
+        preview(
+            &manifest(),
+            "export function register() { while (true) {} }"
+        )
+        .is_err()
+    );
+    assert!(start.elapsed() < std::time::Duration::from_secs(3));
+}
+
+#[test]
+fn arbitrary_html_is_not_accepted_as_ui() {
+    assert!(preview(&manifest(), "export function register(mint) { mint.ui.set('side_panel', {type:'html', html:'<script>bad</script>'}); }").is_err());
+}
+
+#[test]
+fn exported_package_round_trips_only_shareable_source() {
+    let bytes = mint_mod_runtime::pack(&manifest(), "export function register(mint) {}", "Example")
+        .unwrap();
+    let package = mint_mod_runtime::unpack(&bytes).unwrap();
+    assert_eq!(package["manifest"]["id"], "meter");
+    assert_eq!(package["source"], "export function register(mint) {}");
+    assert_eq!(package["readme"], "Example");
+    assert!(package.get("permissionsGranted").is_none());
+}
+
+#[test]
+fn waiting_for_host_io_does_not_spend_callback_cpu_budget() {
+    let code = "export function register(mint) { const text=mint.workspace.read('README.md'); for(let i=0;i<100000;i++){} mint.ui.set('side_panel',{type:'text',text}); }";
+    let engine = mint_mod_runtime::Engine::new(code, &json!({}), |_| {
+        std::thread::sleep(std::time::Duration::from_millis(350));
+        json!({"value":"Read complete"}).to_string()
+    })
+    .expect("Host wait must not be counted as CPU execution");
+    assert_eq!(
+        engine.snapshot().unwrap()["ui"]["side_panel"]["text"],
+        "Read complete"
+    );
+}
+
+#[test]
+fn async_registration_finishes_before_preview() {
+    let value=preview(&manifest(),"export async function register(mint) { await Promise.resolve(); mint.ui.set('side_panel',{type:'text',text:'Ready'}); }").unwrap();
+    assert_eq!(value["ui"]["side_panel"]["text"], "Ready");
+}

package/docs/mods/AUTHORING.md

@@ -0,0 +1,61 @@
+# Mint mod authoring
+
+Load this guide with `mod_help` when the user asks to create or change a Mint mod.
+
+Deliver a working mod through the tools. For a self-contained SDK mod, use the reference below, choose reasonable defaults and send the draft source directly in `mod_validate` arguments. A progress note is at most one short sentence; the source belongs in the tool call. Continue to `mod_publish` after successful validation and report its result. Consult additional workspace files only for a concrete dependency or diagnostic.
+
+1. Call `mod_list` to inspect existing source, hashes, permissions and active revisions.
+2. Create one module exporting `register(mint)`. Draft the manifest with sdkVersion 1, a lowercase kebab-case id, name, version, entry `main.ts` or `main.js`, and a permissions array.
+3. Call `mod_validate` with arguments `{manifest, source, readme}`. Mint retains the draft outside the workspace; validation errors include its path. Preview has no filesystem or tools. Defer those calls to commands or event handlers. Fix diagnostics, with at most three validation attempts; then report any remaining error.
+4. Call `mod_publish` with the same arguments. For an existing mod also include `expectedHash` from mod_list. Publishing checks for disk changes, creates new IDs in `.mint-mods/<id>/` (existing legacy IDs are edited in `mint-mods/<id>/`), and opens the validated revision in this chat. Basic capabilities need no extra activation decision; requested permissions are reviewed by the user.
+5. If tests are requested, add `tests/*.test.ts` exporting `registerTests(test)` and run `mint mods test <id>` (or `/mods test <id>`). Follow [TESTING.md](TESTING.md). Report the folder, activation state and validation/test results with tool output as evidence.
+
+Use these interfaces:
+- `mint.session.usage()` synchronously reads the latest usage snapshot, including before the first event; no special permission or model request.
+- `mint.ui.viewport()` reads the current band dimensions and surface. Subscribe to `ui_resize` to redraw on resizing or panel placement changes. CLI columns are exact; Desktop/Web columns/rows are estimates, with measured widthPx/heightPx. Unknown values are null.
+- `mint.ui.set('above_composer' | 'side_panel', node)`
+- `mint.on(event, handler)` for session_start/end, turn_start/end, pre_tool_use, post_tool_use, usage_update, context_compacted, ui_resize, tool_result.
+- `mint.commands.register(name, handler, description?)`; UI button/input `action` is a registered command name. Input values arrive as handler arguments. Slash commands are `/mods:<id>:<name>`.
+- `mint.state.get(key)` / `mint.state.set(key, JSON value)`: instance state survives restart and stays separate per chat/workspace.
+- `mint.log(message)` for diagnostics.
+- `mint.workspace.read(relativePath)` synchronously reads up to 256 KiB with `workspace.read` permission.
+- `mint.tools.request(action, input)` returns a request ID with `tools.request` permission. Requests run through Mint's tools and approvals; handle their eventual outcome through `tool_result`, matching `requestId`. Pre-tool hooks cannot request tools.
+
+UI node types:
+- text/badge: `{type, text}`
+- stack: `{type:'stack', direction?:'row'|'column', children:[nodes]}`
+- button: `{type:'button', label, action}`
+- input: `{type:'input', label, action, value?}`; Enter submits.
+- progress: `{type:'progress', label, value:number, max:number}`
+- table: `{type:'table', columns:string[], rows:(string|number|null)[][]}`
+
+All nodes accept `color: 'default' | 'yellow' | 'cyan' | 'blue' | 'magenta' | 'red'`. Colors inherit from stacks; `default` restores normal text. Use a row stack for a one-line band with separately colored labels and plain metrics. Desktop/Web scroll narrow rows horizontally; CLI truncates at terminal width. Arbitrary CSS, HTML and ANSI escapes are not supported.
+
+`usage_update`, `context_compacted` and `turn_end` include:
+- `turnId`, `provider`, `model`, `totalTokens` (accumulated API usage this turn, nullable).
+- `contextUsedTokens` (latest provider-reported input + output), `contextInputTokens`, `contextOutputTokens`, `contextPercent` (all nullable).
+- `contextWindowTokens` (nullable), `contextWindowSource: 'mint_config'`. This window comes from Mint's provider defaults/configuration; it is a planning limit, not discovered model capacity. Never hardcode 200k for every provider.
+- `contextStatus: 'measured' | 'unavailable' | 'compacted'`, `compacted` (whether compaction occurred in this turn).
+- `lastTurnDelta` (signed token change from the prior completed turn; null on the first turn, missing usage, provider/model/window changes, and until turn_end).
+
+`usage.context` is `{tokens, window, percent, basis:'input', lastTurnDelta}` and measures the input answered over by the latest response. `usage.contextIncludingOutput` has the same shape with `basis:'input_output'`. The original flat `contextUsedTokens`, `contextPercent` and `lastTurnDelta` retain the input + output definition for compatibility. Use `usage.context` consistently for a Claude-style Token Weather forecast, including its delta; check tokens for null. Both readings use Mint's planning window.
+
+Context occupancy is a latest-response snapshot; tool results appended afterwards are reflected in the next provider response. Repeated requests resend history: do not sum their token counts to estimate occupancy. Anthropic input includes uncached, cache-read and cache-created tokens. Successful compaction emits `context_compacted` with cleared occupancy; wait for the next measured response rather than retaining the old value. `turn_end` also includes success/cancelled and the final usage snapshot, including when a mod was published after the latest usage_update. Use it to append exactly one history point per turn; keep the last 12 in mint.state for a weather sparkline. Show unavailable text for null measurements/deltas. Reading current usage at registration/session_start initializes a newly created mod without waiting for another turn. UI changes require mint.ui.set; state.set alone does not redraw. Refer to `mint-mods.d.ts` for types.
+
+`pre_tool_use` receives action, input, chatId, workspace and callId; return `{block:'reason'}` to reject, or return nothing to allow. Other observers cannot change tool input. `usage_update.totalTokens` is null when unavailable. `turn_start` resets a per-turn token meter. Use explicit unavailable text rather than inventing usage.
+
+Hot reload is opt-in for the live session: `/mods hot-reload on|off`, or the Mods panel toggle. Refresh/events check local active source for changes, validate in a candidate worker, keep state and replace only the current chat's instance. A bad candidate reports reloadError and leaves the old worker active. Changes to any mod with privileged old/new revisions require source-hash review and explicit activation. Global personal copies stay independent of local source. Closing/cancelling the session clears the reload opt-in and session revision override; the original activation revision remains the default for reopening. Invalidate old UI action IDs on reload. Publishing through mod_publish already validates and activates edits; it does not require hot reload to be enabled.
+
+Modules run in restricted QuickJS with 64 MiB memory and a 250 ms CPU deadline per callback. Use SDK capabilities instead of OS globals. Source is one file; type imports from `@mint/mods` are supported. The built-in `defineMod` is an identity helper; export `register` directly. UI is declarative and renders in React and Ratatui.
+
+Example:
+```ts
+export function register(mint: any) {
+  mint.ui.set('above_composer', {type:'text', text:'Usage unavailable'});
+  mint.on('usage_update', (event: any) => {
+    mint.ui.set('above_composer', {
+      type:'text', text:event.totalTokens == null ? 'Usage unavailable' : `${event.totalTokens} tokens`
+    });
+  });
+}
+```

package/docs/mods/README.md

@@ -0,0 +1,139 @@
+# Mint Mods
+
+Mint Mods are single-file TypeScript or JavaScript extensions that add panels,
+status bands, commands and tool guards. Desktop/Web use React; the full-screen
+CLI renders the same UI definitions in Ratatui. No Node.js installation is
+required to compile or execute mods.
+
+## Create from a prompt
+
+Select a workspace, then ask Mint, for example:
+
+> Create a mod showing this turn's token usage above the composer.
+
+Mint uses `mod_help`, `mod_list`, `mod_validate` and `mod_publish` to prepare and
+preview the source. Basic mods open in the current chat after successful
+validation. Workspace reads and requests to existing tools require a separate
+permission decision. Drafts are retained beside Mint's configuration under
+`mods/workspaces/<workspace-hash>/drafts/`; validation errors include their path.
+A failed draft never replaces the active revision.
+
+Source is stored in `<workspace>/.mint-mods/<id>/` with `manifest.json`, `main.ts`
+(or `main.js`) and `README.md`. This repository ignores workspace-local mods;
+put shareable examples in `examples/mods/` or export a `.mintmod` package.
+Other repositories may choose to track `.mint-mods/` to share source with their
+team. Merely cloning a repository or importing a package does not enable its mods.
+
+Compiled source, immutable revisions, activation decisions and per-chat state
+are kept beside Mint's configuration under `mods/`, outside the workspace.
+Activation and state use the canonical workspace identity. A global activation
+installs a personal copy; changes in the original workspace do not silently
+update that copy. Source changes keep the old active revision until validated
+and enabled again, or successfully reloaded in an opted-in session. Special permission decisions belong to the exact source and
+manifest hash.
+
+## Source directory compatibility
+
+New mods and imports for new IDs are created in `<workspace>/.mint-mods/<id>/`.
+Mint also discovers existing `mint-mods/<id>/` folders during the transition.
+Edits, replacement imports, tests and rollback use the selected mod's existing
+folder; Mint does not move it automatically.
+
+If both folders contain the same ID, `.mint-mods` takes precedence and the ID
+appears once. An invalid preferred copy reports an error rather than falling
+back to a legacy copy. To move a legacy mod yourself, move its whole folder
+(including tests) into `.mint-mods`, keeping its ID and source unchanged.
+Activation, approvals and saved state remain tied to the workspace, chat and
+content revision. A changed revision still follows the usual review rules.
+
+## Manage
+
+Type `/mods` in interactive chat to open the mod manager on Full-Screen TUI,
+Desktop and Web. It shows total and active mod counts. Select a mod with the
+arrow keys and Enter in the TUI, or select the displayed choices on Desktop/Web,
+then choose **Enable for this chat** or **Disable for this chat**. Mods with
+permissions require a separate approval before enabling. After a successful
+change, the menu closes, focus returns to the composer, and chat displays
+`[Mods] Enabled/Disabled <id> for this chat.` Reopen `/mods` to see updated counts,
+or use `/mods list` for a text listing.
+
+Use **Mods** above the composer on Desktop/Web to inspect source, diagnostics,
+permissions and revisions; enable for the current chat, workspace or globally;
+export/import `.mintmod` packages; or restore a source revision.
+
+```sh
+mint mods list
+mint mods source token-meter
+mint mods validate token-meter
+mint mods test task-checklist
+mint mods --chat <chat-id> usage
+mint mods enable token-meter
+mint mods enable task-checklist workspace
+mint mods enable custom-reader chat --grant-permissions
+mint mods disable token-meter
+mint mods logs token-meter
+mint mods revisions token-meter
+mint mods rollback token-meter <revision-hash>
+mint mods export token-meter token-meter.mintmod
+mint mods import token-meter.mintmod
+mint mods import token-meter.mintmod --replace
+mint mods --chat <chat-id> list
+```
+
+In interactive chat use `/mods hot-reload on|off` to watch active basic mods for this session; Desktop/Web offer a Hot reload toggle. Invalid changes keep the working revision and report reload diagnostics. Privileged changes still require review. Closing the session clears the opt-in and temporary revision override.
+
+Use `mint mods test <id>` or `/mods test <id>` for runtime tests; Desktop/Web have Run tests with per-case results. Tests never activate mods or perform real filesystem/tool operations. See [TESTING.md](TESTING.md).
+
+In interactive chat use `/mods export <id> [file]`,
+`/mods import <file> [--replace]`, and `/mods:<id>:<command> [value]`.
+Quote paths containing spaces. F7 opens the
+terminal panels; Tab/Shift+Tab select a control, Enter activates it, and Escape
+returns to chat. Input controls accept text before Enter. In a narrow terminal
+the panel overlays the transcript while retaining the composer. `/mods run-tools`
+reviews queued tool requests; the standalone equivalent is `mint mods run-tools`.
+
+Restore changes source; review and enable the restored revision separately.
+Permission approval is never included in exported packages.
+
+## Examples and SDK
+
+Copy a folder from `examples/mods/` into your workspace's `.mint-mods/` directory:
+
+- `token-meter`: displays actual usage, with explicit unavailable state.
+- `task-checklist`: input, button and table backed by per-chat state.
+- `tool-guard`: blocks recursive `rm` commands as an example guard; it is not a
+  comprehensive shell security policy.
+
+Read [AUTHORING.md](AUTHORING.md) for the entrypoint, events and workflow, and
+[mint-mods.d.ts](mint-mods.d.ts) for the TypeScript interface.
+
+## Runtime and limits
+
+Each instance runs in its own process with a restricted QuickJS runtime. The
+SDK grants access through Mint; it does not provide Node.js, direct shell,
+filesystem, network or browser DOM access. The host checks capabilities even
+when a mod bypasses its JavaScript SDK wrappers. This is process separation and
+capability restriction, not an OS sandbox for native-runtime vulnerabilities.
+
+The runtime caps memory at 64 MiB and callback execution at 250 ms, with a
+three-second IPC deadline. UI trees are limited to 256 nodes, 12 nesting levels
+and 64 KiB. State/output is limited to 256 KiB; source to 512 KiB. Packages are
+limited to 1 MiB and contain only manifest, entry and optional README. External
+imports, additional package entries and symlinked sources are rejected.
+
+Tool requests pass through Mint's existing tools, permissions, disabled-tool
+checks and plan-mode restrictions. A mod never grants itself permissions.
+Pre-tool hooks may observe or block; they cannot request tools or rewrite tool
+inputs. A failed pre-tool hook blocks subsequent calls until the mod is fixed
+or disabled. Other observer errors stop the affected instance.
+
+## Packaging
+
+The CLI package builds `mint` and `mint-mod-host`. The desktop executable also
+contains an internal host entrypoint, so bundled Desktop installations can
+start isolated workers without an external Node executable or sidecar path.
+The Web server uses the same host launcher on the server machine.
+
+Context indicators can read `mint.session.usage()` immediately and consume `usage_update`, `context_compacted`, and `turn_end` with nullable latest context tokens, Mint's planning window, percentage and signed completed-turn delta. UI nodes support five named colors and row stacks in CLI, Desktop and Web. See [authoring contract](AUTHORING.md) and [SDK types](mint-mods.d.ts). Anthropic normalization follows [the provider's prompt-cache usage fields](https://platform.claude.com/docs/en/build-with-claude/prompt-caching).
+
+For Claude-style context readings, use `usage.context` (latest input). `usage.contextIncludingOutput` and the existing flat fields include output as well. `mint.ui.viewport()` and `ui_resize` support responsive bands; graphical text dimensions are estimates while pixel dimensions are measured.

package/docs/mods/TESTING.md

@@ -0,0 +1,56 @@
+# Testing Mint mods
+
+Keep tests beside the mod in `.mint-mods/<id>/tests/*.test.ts` or `*.test.js`.
+Existing mods in `mint-mods/<id>/` use the same `tests/` layout.
+Export `registerTests(test)`; each named case runs in a fresh QuickJS instance
+using the actual mod source and SDK. Tests never enable a mod or change its
+saved state. Type imports from `@mint/mods` work as in main.ts.
+
+```ts
+import type { TestRegistrar } from '@mint/mods'
+
+export function registerTests(test: TestRegistrar) {
+  test('adds an item', async ({ command, state, equal }) => {
+    await command('add', 'Review changes')
+    equal(state('task'), 'Review changes')
+  })
+
+  test('usage updates the band', async ({ emit, ui, equal }) => {
+    await emit('usage_update', {
+      context: { tokens: 134400, window: 200000, percent: 67.2,
+        basis: 'input', lastTurnDelta: null },
+    })
+    equal(ui('above_composer')?.type, 'stack')
+  }, {
+    usage: { context: { tokens: 36100, window: 200000, percent: 18.05,
+      basis: 'input', lastTurnDelta: null } },
+    viewport: { surface: 'terminal', columns: 120, rows: 35 },
+  })
+}
+```
+
+Choose assertions that match your mod; the examples assume commands/state/UI
+that the author implements. `emit` dispatches a supported lifecycle event and
+returns its result (including pre-tool block decisions). For usage_update,
+context_compacted and turn_end it first updates what session.usage returns.
+`command` invokes a registered mod command. `ui(slot)` and `state(key)` return
+copies, or null when absent. `equal` checks deep JSON equality and accepts an
+optional failure message.
+
+The third test argument supplies initial `usage`, `viewport`, `state` and
+`files` fixtures. File fixtures map relative paths to text and require the
+manifest's workspace.read permission. There is no access to real files,
+network, model calls or tools; simulate tool_result events when needed.
+Include all usage fields your mod reads. Defaults explicitly mark usage and
+viewport as unavailable.
+
+Run `mint mods test <id>`, `/mods test <id>`, or Run tests in the Desktop/Web
+Mods panel. CLI returns a nonzero exit status if any case fails. Results name
+each case and file and report assertion/runtime errors. Compilation or missing
+tests are errors rather than successful empty runs. Tests use current workspace
+source, independently of its active revision. Keep tests in the repository;
+the compact .mintmod export format contains only the entry, manifest and README.
+
+Limits: 32 test files, 64 uniquely named cases per file, 512 KiB per source,
+64 MiB memory per instance and 250 ms CPU per registration/case. Host fixtures
+perform no external I/O. Infinite loops and invalid UI fail the case.

package/docs/mods/mint-mods.d.ts

@@ -0,0 +1,66 @@
+declare module '@mint/mods' {
+  export type Slot = 'above_composer' | 'side_panel'
+  export type Color = 'default' | 'yellow' | 'cyan' | 'blue' | 'magenta' | 'red'
+  export type Node = { type: 'text' | 'stack' | 'badge' | 'button' | 'input' | 'progress' | 'table'; color?: Color; direction?: 'row' | 'column'; text?: string; label?: string; action?: string; value?: string | number; max?: number; columns?: string[]; rows?: (string | number | null)[][]; children?: Node[] }
+  export type Event = 'session_start' | 'session_end' | 'turn_start' | 'turn_end' | 'pre_tool_use' | 'post_tool_use' | 'usage_update' | 'context_compacted' | 'ui_resize' | 'tool_result'
+  export interface Viewport {
+    surface: 'terminal' | 'desktop' | 'web' | null
+    /** Exact text columns in CLI; estimated from pixels on graphical surfaces. */
+    columns: number | null
+    rows: number | null
+    widthPx: number | null
+    heightPx: number | null
+    sidePanelOpen: boolean
+  }
+  export interface ContextReading {
+    tokens: number | null
+    window: number | null
+    percent: number | null
+    basis: 'input' | 'input_output'
+    lastTurnDelta: number | null
+  }
+  export interface UsageEvent {
+    turnId: number
+    /** Accumulated API usage for this turn, not context occupancy. */
+    totalTokens: number | null
+    /** Latest provider-reported input + output; null after compaction or missing usage. */
+    contextUsedTokens: number | null
+    contextInputTokens: number | null
+    contextOutputTokens: number | null
+    /** Mint's configured/conservative planning window, not a provider capacity discovery. */
+    contextWindowTokens: number | null
+    contextWindowSource: 'mint_config'
+    contextPercent: number | null
+    contextStatus: 'measured' | 'unavailable' | 'compacted'
+    provider: string
+    model: string
+    /** Signed difference from previous completed turn; provided only on turn_end. */
+    lastTurnDelta: number | null
+    compacted: boolean
+    /** Last response's input context, matching the Claude-style reading. */
+    context: ContextReading & { basis: 'input' }
+    contextIncludingOutput: ContextReading & { basis: 'input_output' }
+  }
+  export type EventPayload<E extends Event> = E extends 'turn_end'
+    ? UsageEvent & { success: boolean; cancelled: boolean }
+    : E extends 'usage_update' | 'context_compacted' ? UsageEvent : E extends 'ui_resize' ? Viewport : any
+  export interface Mint {
+    session: { usage(): UsageEvent }
+    on<E extends Event>(event: E, handler: (event: EventPayload<E>) => void | { block: string } | Promise<void | { block: string }>): void
+    ui: { set(slot: Slot, tree: Node): void; viewport(): Viewport }
+    commands: { register(name: string, handler: (value?: string) => unknown, description?: string): void }
+    state: { get(key: string): any; set(key: string, value: unknown): void }
+    workspace: { read(path: string): string }
+    tools: { request(action: string, input?: Record<string, unknown>): string }
+    log(message: unknown): void
+  }
+  export interface TestContext {
+    mint: Mint
+    emit<E extends Event>(event: E, payload?: Partial<EventPayload<E>>): Promise<any>
+    command(name: string, value?: unknown): Promise<any>
+    ui(slot: Slot): Node | null
+    state(key: string): any
+    equal(actual: unknown, expected: unknown, message?: string): void
+  }
+  export type TestRegistrar = (name: string, run: (context: TestContext) => void | Promise<void>, fixtures?: { usage?: Partial<UsageEvent>; viewport?: Partial<Viewport>; files?: Record<string, string>; state?: Record<string, unknown> }) => void
+}

package/examples/device-mcp/README.md

@@ -0,0 +1,22 @@
+# Mint Device MCP example
+
+This stdio MCP server simulates one motor and camera. It requires Node.js 18+ and has no npm dependencies. It never accesses real hardware. `mock-device.mjs` is the adapter seam; `server.mjs` owns MCP framing, tool descriptions, schemas, and results.
+
+From the repository root, register its absolute path (replace `/path/to/Mint-CLI`):
+
+```bash
+mint mcp add mock-device node --args /path/to/Mint-CLI/examples/device-mcp/server.mjs
+mint mcp allow mock-device '*'
+```
+
+In agent chat, ask: “Set mock-device to 100 RPM and confirm its observed speed”, “Stop mock-device and confirm zero RPM”, or “Capture a photo from mock-device”. The photo is a generated PNG sample. The allow command grants all tools on this example server; omit it to approve calls individually.
+
+For the raw CLI, use:
+
+```bash
+mint mcp call mock-device set_speed --arguments '{"deviceId":"mock-device","rpm":100}'
+```
+
+The raw call returns the MCP receipt after schema validation. Automatic waiting and `DeviceState` events apply to agent chat. Read `get_status` with the receipt's `operationId` when using raw calls; repeated separate CLI processes start fresh mock servers and cannot preserve the simulated operation. An agent chat keeps the MCP session alive.
+
+Run the example's protocol tests with `npm run test:device`. See [the Device v1 contract](contract.md) before replacing the mock adapter.