nodmix 2026.5.25

package/docs/superpowers/specs/2026-04-22-tweakcn-custom-theme-import-design.md

@@ -0,0 +1,316 @@
+# Tweakcn Custom Theme Import Design
+
+Status: approved in terminal on 2026-04-22
+
+## Summary
+
+Add exactly one browser-local custom Control UI theme slot that can be imported from a tweakcn share link. The existing built-in theme families remain `claw`, `knot`, and `dash`. The new `custom` family behaves like a normal Nodmix theme family and supports `light`, `dark`, and `system` mode when the imported tweakcn payload includes both light and dark token sets.
+
+The imported theme is stored only in the current browser profile with the rest of the Control UI settings. It is not written to gateway config and does not sync across devices or browsers.
+
+## Problem
+
+The Control UI theme system is currently closed over three hard-coded theme families:
+
+- `ui/src/ui/theme.ts`
+- `ui/src/ui/views/config.ts`
+- `ui/src/styles/base.css`
+
+Users can switch among built-in families and mode variants, but they cannot bring in a theme from tweakcn without editing repo CSS. The requested outcome is smaller than a general theming system: keep the three built-ins and add one user-controlled imported slot that can be replaced from a tweakcn link.
+
+## Goals
+
+- Keep the existing built-in theme families unchanged.
+- Add exactly one imported custom slot, not a theme library.
+- Accept a tweakcn share link or a direct `https://tweakcn.com/r/themes/{id}` URL.
+- Persist the imported theme in browser local storage only.
+- Make the imported slot work with existing `light`, `dark`, and `system` mode controls.
+- Keep failure behavior safe: a bad import never breaks the active UI theme.
+
+## Non goals
+
+- No multi-theme library or browser-local list of imports.
+- No gateway-side persistence or cross-device sync.
+- No arbitrary CSS editor or raw theme JSON editor.
+- No automatic loading of remote font assets from tweakcn.
+- No attempt to support tweakcn payloads that only expose one mode.
+- No repo-wide theming refactor beyond the seams required for the Control UI.
+
+## User decisions already made
+
+- Keep the three built-in themes.
+- Add one tweakcn-powered import slot.
+- Store the imported theme in the browser, not gateway config.
+- Support `light`, `dark`, and `system` for the imported slot.
+- Overwriting the custom slot with the next import is the intended behavior.
+
+## Recommended approach
+
+Add a fourth theme family id, `custom`, to the Control UI theme model. The `custom` family becomes selectable only when a valid tweakcn import is present. The imported payload is normalized into an Nodmix-specific custom theme record and stored in browser local storage with the rest of the UI settings.
+
+At runtime, Nodmix renders a managed `<style>` tag that defines the resolved custom CSS variable blocks:
+
+```css
+:root[data-theme="custom"] { ... }
+:root[data-theme="custom-light"] { ... }
+```
+
+This keeps custom theme variables scoped to the `custom` family and avoids leaking inline CSS variables into the built-in families.
+
+## Architecture
+
+### Theme model
+
+Update `ui/src/ui/theme.ts`:
+
+- Extend `ThemeName` to include `custom`.
+- Extend `ResolvedTheme` to include `custom` and `custom-light`.
+- Extend `VALID_THEME_NAMES`.
+- Update `resolveTheme()` so `custom` mirrors the existing family behavior:
+  - `custom + dark` -> `custom`
+  - `custom + light` -> `custom-light`
+  - `custom + system` -> `custom` or `custom-light` based on OS preference
+
+No legacy aliases are added for `custom`.
+
+### Persistence model
+
+Extend `UiSettings` persistence in `ui/src/ui/storage.ts` with one optional custom-theme payload:
+
+- `customTheme?: ImportedCustomTheme`
+
+Recommended stored shape:
+
+```ts
+type ImportedCustomTheme = {
+  sourceUrl: string;
+  themeId: string;
+  label: string;
+  importedAt: string;
+  light: Record<string, string>;
+  dark: Record<string, string>;
+};
+```
+
+Notes:
+
+- `sourceUrl` stores the original user input after normalization.
+- `themeId` is the tweakcn theme id extracted from the URL.
+- `label` is the tweakcn `name` field when present, else `Custom`.
+- `light` and `dark` are already normalized Nodmix token maps, not raw tweakcn payloads.
+- The imported payload lives beside other browser-local settings and is serialized in the same local-storage document.
+- If stored custom-theme data is missing or invalid on load, ignore the payload and fall back to `theme: "claw"` when the persisted family was `custom`.
+
+### Runtime application
+
+Add a narrow custom-theme stylesheet manager in the Control UI runtime, owned near `ui/src/ui/app-settings.ts` and `ui/src/ui/theme.ts`.
+
+Responsibilities:
+
+- Create or update one stable `<style id="nodmix-custom-theme">` tag in `document.head`.
+- Emit CSS only when a valid custom theme payload exists.
+- Remove the style tag content when the payload is cleared.
+- Keep built-in family CSS in `ui/src/styles/base.css`; do not splice imported tokens into the checked-in stylesheet.
+
+This manager runs whenever settings are loaded, saved, imported, or cleared.
+
+### Light-mode selectors
+
+Implementation should prefer `data-theme-mode="light"` for cross-family light styling rather than special-casing `custom-light`. If an existing selector is pinned to `data-theme="light"` and needs to apply to every light family, broaden it as part of this work.
+
+## Import UX
+
+Update `ui/src/ui/views/config.ts` in the `Appearance` section:
+
+- Add a `Custom` theme card beside `Claw`, `Knot`, and `Dash`.
+- Show the card as disabled when no imported custom theme exists.
+- Add an import panel under the theme grid with:
+  - one text input for a tweakcn share link or `/r/themes/{id}` URL
+  - one `Import` button
+  - one `Replace` path when a custom payload already exists
+  - one `Clear` action when a custom payload already exists
+- Show the imported theme label and source host when a payload exists.
+- If the active theme is `custom`, importing a replacement applies immediately.
+- If the active theme is not `custom`, importing only stores the new payload until the user selects the `Custom` card.
+
+The quick settings theme picker in `ui/src/ui/views/config-quick.ts` should also show `Custom` only when a payload exists.
+
+## URL parsing and remote fetch
+
+The browser import path accepts:
+
+- `https://tweakcn.com/themes/{id}`
+- `https://tweakcn.com/r/themes/{id}`
+
+Implementation should normalize both forms to:
+
+- `https://tweakcn.com/r/themes/{id}`
+
+The browser then fetches the normalized `/r/themes/{id}` endpoint directly.
+
+Use a narrow schema validator for the external payload. A zod schema is preferred because this is an untrusted external boundary.
+
+Required remote fields:
+
+- top-level `name` as optional string
+- `cssVars.theme` as optional object
+- `cssVars.light` as object
+- `cssVars.dark` as object
+
+If either `cssVars.light` or `cssVars.dark` is missing, reject the import. This is deliberate: the approved product behavior is full mode support, not best-effort synthesis of a missing side.
+
+## Token mapping
+
+Do not mirror tweakcn variables blindly. Normalize a bounded subset into Nodmix tokens and derive the rest in a helper.
+
+### Tokens imported directly
+
+From each tweakcn mode block:
+
+- `background`
+- `foreground`
+- `card`
+- `card-foreground`
+- `popover`
+- `popover-foreground`
+- `primary`
+- `primary-foreground`
+- `secondary`
+- `secondary-foreground`
+- `muted`
+- `muted-foreground`
+- `accent`
+- `accent-foreground`
+- `destructive`
+- `destructive-foreground`
+- `border`
+- `input`
+- `ring`
+- `radius`
+
+From shared `cssVars.theme` when present:
+
+- `font-sans`
+- `font-mono`
+
+If a mode block overrides `font-sans`, `font-mono`, or `radius`, the mode-local value wins.
+
+### Tokens derived for Nodmix
+
+The importer derives Nodmix-only variables from the imported base colors:
+
+- `--bg-accent`
+- `--bg-elevated`
+- `--bg-hover`
+- `--panel`
+- `--panel-strong`
+- `--panel-hover`
+- `--chrome`
+- `--chrome-strong`
+- `--text`
+- `--text-strong`
+- `--chat-text`
+- `--muted`
+- `--muted-strong`
+- `--accent-hover`
+- `--accent-muted`
+- `--accent-subtle`
+- `--accent-glow`
+- `--focus`
+- `--focus-ring`
+- `--focus-glow`
+- `--secondary`
+- `--secondary-foreground`
+- `--danger`
+- `--danger-muted`
+- `--danger-subtle`
+
+Derivation rules live in a pure helper so they can be tested independently. Exact color-mixing formulas are an implementation detail, but the helper must satisfy two constraints:
+
+- preserve readable contrast close to the imported theme intent
+- produce stable output for the same imported payload
+
+### Tokens ignored in v1
+
+These tweakcn tokens are intentionally ignored in the first version:
+
+- `chart-*`
+- `sidebar-*`
+- `font-serif`
+- `shadow-*`
+- `tracking-*`
+- `letter-spacing`
+- `spacing`
+
+This keeps the scope on the tokens the current Control UI actually needs.
+
+### Fonts
+
+Font stack strings are imported if present, but Nodmix does not load remote font assets in v1. If the imported stack references fonts that are unavailable in the browser, normal fallback behavior applies.
+
+## Failure behavior
+
+Bad imports must fail closed.
+
+- Invalid URL format: show inline validation error, do not fetch.
+- Unsupported host or path shape: show inline validation error, do not fetch.
+- Network failure, non-OK response, or malformed JSON: show inline error, keep current stored payload untouched.
+- Schema failure or missing light/dark blocks: show inline error, keep current stored payload untouched.
+- Clear action:
+  - removes the stored custom payload
+  - removes the managed custom style tag content
+  - if `custom` is active, switches theme family back to `claw`
+- Invalid stored custom payload on first load:
+  - ignore the stored payload
+  - do not emit custom CSS
+  - if persisted theme family was `custom`, fall back to `claw`
+
+At no point should a failed import leave the active document with partial custom CSS variables applied.
+
+## Files expected to change in implementation
+
+Primary files:
+
+- `ui/src/ui/theme.ts`
+- `ui/src/ui/storage.ts`
+- `ui/src/ui/app-settings.ts`
+- `ui/src/ui/views/config.ts`
+- `ui/src/ui/views/config-quick.ts`
+- `ui/src/styles/base.css`
+
+Likely new helpers:
+
+- `ui/src/ui/custom-theme.ts`
+
+Tests:
+
+- `ui/src/ui/app-settings.test.ts`
+- `ui/src/ui/storage.node.test.ts`
+- `ui/src/ui/views/config.browser.test.ts`
+- new focused tests for URL parsing and payload normalization
+
+## Testing
+
+Minimum implementation coverage:
+
+- parse share-link URL into tweakcn theme id
+- normalize `/themes/{id}` and `/r/themes/{id}` into the fetch URL
+- reject unsupported hosts and malformed ids
+- validate tweakcn payload shape
+- map a valid tweakcn payload into normalized Nodmix light and dark token maps
+- load and save the custom payload in browser-local settings
+- resolve `custom` for `light`, `dark`, and `system`
+- disable `Custom` selection when no payload exists
+- apply imported theme immediately when `custom` is already active
+- fall back to `claw` when the active custom theme is cleared
+
+Manual verification target:
+
+- import a known tweakcn theme from Settings
+- switch among `light`, `dark`, and `system`
+- switch between `custom` and the built-in families
+- reload the page and confirm the imported custom theme persists locally
+
+## Rollout notes
+
+This feature is intentionally small. If users later ask for multiple imported themes, rename, export, or cross-device sync, treat that as a follow-on design. Do not pre-build a theme library abstraction in this implementation.

package/docs/tools/acp-agents-setup.md

@@ -0,0 +1,352 @@
+---
+summary: "Setting up ACP agents: acpx harness config, plugin setup, permissions"
+read_when:
+  - Installing or configuring the acpx harness for Claude Code / Codex / Gemini CLI
+  - Enabling the plugin-tools or Nodmix-tools MCP bridge
+  - Configuring ACP permission modes
+title: "ACP agents — setup"
+---
+
+For the overview, operator runbook, and concepts, see [ACP agents](/tools/acp-agents).
+
+The sections below cover acpx harness config, plugin setup for the MCP bridges, and permission configuration.
+
+Use this page only when you are setting up the ACP/acpx route. For native Codex
+app-server runtime config, use [Codex harness](/plugins/codex-harness). For
+OpenAI API keys or Codex OAuth model-provider config, use
+[OpenAI](/providers/openai).
+
+Codex has two Nodmix routes:
+
+| Route                      | Config/command                                         | Setup page                              |
+| -------------------------- | ------------------------------------------------------ | --------------------------------------- |
+| Native Codex app-server    | `/codex ...`, `openai/gpt-*` agent refs                | [Codex harness](/plugins/codex-harness) |
+| Explicit Codex ACP adapter | `/acp spawn codex`, `runtime: "acp", agentId: "codex"` | This page                               |
+
+Prefer the native route unless you explicitly need ACP/acpx behavior.
+
+## acpx harness support (current)
+
+Current acpx built-in harness aliases:
+
+- `claude`
+- `codex`
+- `copilot`
+- `cursor` (Cursor CLI: `cursor-agent acp`)
+- `droid`
+- `gemini`
+- `iflow`
+- `kilocode`
+- `kimi`
+- `kiro`
+- `nodmix`
+- `opencode`
+- `pi`
+- `qwen`
+
+When Nodmix uses the acpx backend, prefer these values for `agentId` unless your acpx config defines custom agent aliases.
+If your local Cursor install still exposes ACP as `agent acp`, override the `cursor` agent command in your acpx config instead of changing the built-in default.
+
+Direct acpx CLI usage can also target arbitrary adapters via `--agent <command>`, but that raw escape hatch is an acpx CLI feature (not the normal Nodmix `agentId` path).
+
+Model control is adapter-capability dependent. Codex ACP model refs are
+normalized by Nodmix before startup. Other harnesses need ACP `models` plus
+`session/set_model` support; if a harness exposes neither that ACP capability
+nor its own startup model flag, Nodmix/acpx cannot force a model selection.
+
+## Required config
+
+Core ACP baseline:
+
+```json5
+{
+  acp: {
+    enabled: true,
+    // Optional. Default is true; set false to pause ACP dispatch while keeping /acp controls.
+    dispatch: { enabled: true },
+    backend: "acpx",
+    defaultAgent: "codex",
+    allowedAgents: [
+      "claude",
+      "codex",
+      "copilot",
+      "cursor",
+      "droid",
+      "gemini",
+      "iflow",
+      "kilocode",
+      "kimi",
+      "kiro",
+      "nodmix",
+      "opencode",
+      "pi",
+      "qwen",
+    ],
+    maxConcurrentSessions: 8,
+    stream: {
+      coalesceIdleMs: 300,
+      maxChunkChars: 1200,
+    },
+    runtime: {
+      ttlMinutes: 120,
+    },
+  },
+}
+```
+
+Thread binding config is channel-adapter specific. Example for Discord:
+
+```json5
+{
+  session: {
+    threadBindings: {
+      enabled: true,
+      idleHours: 24,
+      maxAgeHours: 0,
+    },
+  },
+  channels: {
+    discord: {
+      threadBindings: {
+        enabled: true,
+        spawnSessions: true,
+      },
+    },
+  },
+}
+```
+
+If thread-bound ACP spawn does not work, verify the adapter feature flag first:
+
+- Discord: `channels.discord.threadBindings.spawnSessions=true`
+
+Current-conversation binds do not require child-thread creation. They require an active conversation context and a channel adapter that exposes ACP conversation bindings.
+
+See [Configuration Reference](/gateway/configuration-reference).
+
+## Plugin setup for acpx backend
+
+Packaged installs use the official `@nodmix/acpx` runtime plugin for ACP.
+Install and enable it before using ACP harness sessions:
+
+```bash
+nodmix plugins install @nodmix/acpx
+nodmix config set plugins.entries.acpx.enabled true
+```
+
+Source checkouts can also use the local workspace plugin after `pnpm install`.
+
+Start with:
+
+```text
+/acp doctor
+```
+
+If you disabled `acpx`, denied it via `plugins.allow` / `plugins.deny`, or want
+to switch back to the packaged plugin, use the explicit package path:
+
+```bash
+nodmix plugins install @nodmix/acpx
+nodmix config set plugins.entries.acpx.enabled true
+```
+
+Local workspace install during development:
+
+```bash
+nodmix plugins install ./path/to/local/acpx-plugin
+```
+
+Then verify backend health:
+
+```text
+/acp doctor
+```
+
+### acpx command and version configuration
+
+By default, the `acpx` plugin registers the embedded ACP backend during Gateway
+startup and waits for the embedded runtime startup probe before the gateway
+`ready` signal. Set `NODMIX_ACPX_RUNTIME_STARTUP_PROBE=0` or
+`NODMIX_SKIP_ACPX_RUNTIME_PROBE=1` only for scripts or environments that
+intentionally keep the startup probe disabled. Run `/acp doctor` for an explicit
+on-demand probe.
+
+Override the command or version in plugin config:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "acpx": {
+        "enabled": true,
+        "config": {
+          "command": "../acpx/dist/cli.js",
+          "expectedVersion": "any"
+        }
+      }
+    }
+  }
+}
+```
+
+- `command` accepts an absolute path, relative path (resolved from the Nodmix workspace), or command name.
+- `expectedVersion: "any"` disables strict version matching.
+- Custom `command` paths disable plugin-local auto-install.
+
+Override an individual ACP agent command with structured arguments when a path
+or flag value should remain one argv token:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "acpx": {
+        "enabled": true,
+        "config": {
+          "agents": {
+            "claude": {
+              "command": "node",
+              "args": ["/path/to/custom adapter.mjs", "--verbose"]
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+- `agents.<id>.command` is the executable or existing command string for that ACP agent.
+- `agents.<id>.args` is optional. Each array item is shell-quoted before Nodmix passes it through the current acpx command-string registry.
+
+See [Plugins](/tools/plugin).
+
+### Automatic dependency install
+
+When you install Nodmix globally with `npm install -g nodmix`, the acpx
+runtime dependencies (platform-specific binaries) are installed automatically
+via a postinstall hook. If the automatic install fails, the gateway still starts
+normally and reports the missing dependency through `nodmix acp doctor`.
+
+### Plugin tools MCP bridge
+
+By default, ACPX sessions do **not** expose Nodmix plugin-registered tools to
+the ACP harness.
+
+If you want ACP agents such as Codex or Claude Code to call installed
+Nodmix plugin tools such as memory recall/store, enable the dedicated bridge:
+
+```bash
+nodmix config set plugins.entries.acpx.config.pluginToolsMcpBridge true
+```
+
+What this does:
+
+- Injects a built-in MCP server named `nodmix-plugin-tools` into ACPX session
+  bootstrap.
+- Exposes plugin tools already registered by installed and enabled Nodmix
+  plugins.
+- Keeps the feature explicit and default-off.
+
+Security and trust notes:
+
+- This expands the ACP harness tool surface.
+- ACP agents get access only to plugin tools already active in the gateway.
+- Treat this as the same trust boundary as letting those plugins execute in
+  Nodmix itself.
+- Review installed plugins before enabling it.
+
+Custom `mcpServers` still work as before. The built-in plugin-tools bridge is an
+additional opt-in convenience, not a replacement for generic MCP server config.
+
+### Nodmix tools MCP bridge
+
+By default, ACPX sessions also do **not** expose built-in Nodmix tools through
+MCP. Enable the separate core-tools bridge when an ACP agent needs selected
+built-in tools such as `cron`:
+
+```bash
+nodmix config set plugins.entries.acpx.config.openClawToolsMcpBridge true
+```
+
+What this does:
+
+- Injects a built-in MCP server named `nodmix-tools` into ACPX session
+  bootstrap.
+- Exposes selected built-in Nodmix tools. The initial server exposes `cron`.
+- Keeps core-tool exposure explicit and default-off.
+
+### Runtime operation timeout configuration
+
+The `acpx` plugin gives embedded runtime startup and control operations 120
+seconds by default. This gives slower harnesses such as Gemini CLI enough time
+to complete ACP startup and initialization. Override it if your host needs a
+different operation limit:
+
+```bash
+nodmix config set plugins.entries.acpx.config.timeoutSeconds 180
+```
+
+Runtime turns use Nodmix agent/run timeouts, including `/acp timeout` and
+`sessions_spawn.timeoutSeconds`. Restart the gateway after changing this value.
+
+### Health probe agent configuration
+
+When `/acp doctor` or the startup probe checks the backend, the bundled `acpx`
+plugin probes one harness agent. If `acp.allowedAgents` is set, it defaults to
+the first allowed agent; otherwise it defaults to `codex`. If your deployment
+needs a different ACP agent for health checks, set the probe agent explicitly:
+
+```bash
+nodmix config set plugins.entries.acpx.config.probeAgent claude
+```
+
+Restart the gateway after changing this value.
+
+## Permission configuration
+
+ACP sessions run non-interactively — there is no TTY to approve or deny file-write and shell-exec permission prompts. The acpx plugin provides two config keys that control how permissions are handled:
+
+These ACPX harness permissions are separate from Nodmix exec approvals and separate from CLI-backend vendor bypass flags such as Claude CLI `--permission-mode bypassPermissions`. ACPX `approve-all` is the harness-level break-glass switch for ACP sessions.
+
+### `permissionMode`
+
+Controls which operations the harness agent can perform without prompting.
+
+| Value           | Behavior                                                  |
+| --------------- | --------------------------------------------------------- |
+| `approve-all`   | Auto-approve all file writes and shell commands.          |
+| `approve-reads` | Auto-approve reads only; writes and exec require prompts. |
+| `deny-all`      | Deny all permission prompts.                              |
+
+### `nonInteractivePermissions`
+
+Controls what happens when a permission prompt would be shown but no interactive TTY is available (which is always the case for ACP sessions).
+
+| Value  | Behavior                                                          |
+| ------ | ----------------------------------------------------------------- |
+| `fail` | Abort the session with `AcpRuntimeError`. **(default)**           |
+| `deny` | Silently deny the permission and continue (graceful degradation). |
+
+### Configuration
+
+Set via plugin config:
+
+```bash
+nodmix config set plugins.entries.acpx.config.permissionMode approve-all
+nodmix config set plugins.entries.acpx.config.nonInteractivePermissions fail
+```
+
+Restart the gateway after changing these values.
+
+<Warning>
+Nodmix defaults to `permissionMode=approve-reads` and `nonInteractivePermissions=fail`. In non-interactive ACP sessions, any write or exec that triggers a permission prompt can fail with `AcpRuntimeError: Permission prompt unavailable in non-interactive mode`.
+
+If you need to restrict permissions, set `nonInteractivePermissions` to `deny` so sessions degrade gracefully instead of crashing.
+</Warning>
+
+## Related
+
+- [ACP agents](/tools/acp-agents) — overview, operator runbook, concepts
+- [Sub-agents](/tools/subagents)
+- [Multi-agent routing](/concepts/multi-agent)