Skip to content

The open-source full-stack studio for Opus 5.5 motion video. Reverse engineering for any video. Code video with HTML: recreate, edit and render. BYOA + BYOK · Motion.md · Images, Video, Music & Voice.

fix(agents): bin path override + envOverride + Windows shell launch (#17)

Joey-nexufec591b38cbb
diff --git a/src/app/api/convert/route.ts b/src/app/api/convert/route.ts
index b4e03678..00dbd5c5 100644
--- a/src/app/api/convert/route.ts
+++ b/src/app/api/convert/route.ts
@@ -13,6 +13,12 @@ type Body = {
format?: string;
model?: string;
cwd?: string;
+ /**
+ * Optional absolute path to the agent binary. The Settings UI lets the
+ * user override auto-detection when their CLI lives somewhere our PATH
+ * scan doesn't cover (Scoop on Windows, custom installs, etc.).
+ */
+ binOverride?: string;
/** When the task already has a generated HTML, the client sends both the
* prior HTML and the prior content. The agent is then asked for a
* minimal-diff edit (preserve design, only change what the content diff
@@ -69,6 +75,7 @@ export async function POST(req: NextRequest) {
format = "text",
model,
cwd,
+ binOverride,
editFromHtml,
editFromContent,
} = body;
@@ -103,6 +110,7 @@ export async function POST(req: NextRequest) {
prompt,
model,
cwd,
+ binOverride,
signal: abortCtl.signal,
});
diff --git a/src/app/api/draft/route.ts b/src/app/api/draft/route.ts
index 620e843a..806f5a6e 100644
--- a/src/app/api/draft/route.ts
+++ b/src/app/api/draft/route.ts
@@ -12,6 +12,8 @@ type Body = {
* continue the user's voice instead of writing in isolation. */
context?: string;
model?: string;
+ /** Optional absolute path to the agent binary; see /api/convert. */
+ binOverride?: string;
};
function buildDraftPrompt(args: { instruction: string; context: string }): string {
@@ -41,7 +43,7 @@ export async function POST(req: NextRequest) {
} catch {
return new Response("invalid JSON body", { status: 400 });
}
- const { agent, instruction, context = "", model } = body;
+ const { agent, instruction, context = "", model, binOverride } = body;
if (!agent || !instruction?.trim()) {
return new Response("missing required fields: agent, instruction", {
status: 400,
@@ -57,6 +59,7 @@ export async function POST(req: NextRequest) {
agent,
prompt,
model,
+ binOverride,
signal: abortCtl.signal,
});
diff --git a/src/components/settings-modal.tsx b/src/components/settings-modal.tsx
index b2626535..4ded0203 100644
--- a/src/components/settings-modal.tsx
+++ b/src/components/settings-modal.tsx
@@ -144,9 +144,11 @@ function AgentSection() {
const setSelectedAgent = useStore((s) => s.setSelectedAgent);
const setAgents = useStore((s) => s.setAgents);
const setAgentModel = useStore((s) => s.setAgentModel);
+ const setAgentBinOverride = useStore((s) => s.setAgentBinOverride);
const agents = useStore((s) => s.agents);
const selected = useStore((s) => s.selectedAgent);
const agentModels = useStore((s) => s.agentModels);
+ const agentBinOverrides = useStore((s) => s.agentBinOverrides);
const t = useT();
const [loading, setLoading] = useState(false);
@@ -234,6 +236,14 @@ function AgentSection() {
/>
)}
+ {selectedAgent && (
+ <CustomBinPath
+ agent={selectedAgent}
+ value={agentBinOverrides[selectedAgent.id] ?? ""}
+ onChange={(p) => setAgentBinOverride(selectedAgent.id, p)}
+ />
+ )}
+
{missing.length > 0 && (
<>
<div className="mt-6 mb-2 flex items-center gap-2 text-[11px] uppercase tracking-[0.18em] text-[var(--ink-faint)]">
@@ -429,6 +439,97 @@ function ModelPicker({
);
}
+function CustomBinPath({
+ agent,
+ value,
+ onChange,
+}: {
+ agent: AgentInfo;
+ value: string;
+ onChange: (path: string) => void;
+}) {
+ const t = useT();
+ const [draft, setDraft] = useState(value);
+ // Keep the local input in sync if the persisted value changes from elsewhere
+ // (e.g. agent switch). Avoid clobbering an in-progress edit.
+ useEffect(() => {
+ setDraft(value);
+ }, [value, agent.id]);
+ // Best-effort platform sniff for the placeholder hint. The actual path
+ // resolution happens server-side in `resolveBinForAgent`.
+ const isWindows = typeof navigator !== "undefined" && /Win/i.test(navigator.platform);
+ const placeholder = isWindows
+ ? "C:\\Users\\you\\scoop\\apps\\nodejs\\current\\claude.cmd"
+ : "/usr/local/bin/claude";
+ const detected = agent.path;
+ const dirty = draft.trim() !== value.trim();
+ return (
+ <div
+ className="mt-3 rounded-2xl p-4"
+ style={{ background: "var(--paper)", border: "1px solid var(--line-faint)" }}
+ >
+ <div className="flex items-baseline justify-between gap-3">
+ <div>
+ <div className="text-[11px] uppercase tracking-[0.18em] text-[var(--ink-faint)]">
+ {t("agent.customBin.eyebrow")}
+ </div>
+ <div className="text-[12.5px] text-[var(--ink-soft)] mt-0.5">
+ {t("agent.customBin.subtitle", { agent: agent.label })}
+ </div>
+ </div>
+ {detected && (
+ <div className="text-[10.5px] text-[var(--ink-mute)] max-w-[260px] text-right leading-snug">
+ {t("agent.customBin.detected")}
+ <code className="ml-1 break-all font-mono text-[10px] text-[var(--ink-soft)]">{detected}</code>
+ </div>
+ )}
+ </div>
+ <div className="mt-2 flex items-center gap-2">
+ <input
+ type="text"
+ value={draft}
+ onChange={(e) => setDraft(e.target.value)}
+ onBlur={() => onChange(draft)}
+ onKeyDown={(e) => {
+ if (e.key === "Enter") onChange(draft);
+ if (e.key === "Escape") setDraft(value);
+ }}
+ placeholder={placeholder}
+ className="min-w-0 flex-1 rounded-lg px-3 py-1.5 font-mono text-[12px] outline-none"
+ style={{
+ background: "var(--surface)",
+ border: "1px solid var(--line)",
+ color: "var(--ink)",
+ }}
+ />
+ {value && (
+ <button
+ onClick={() => {
+ setDraft("");
+ onChange("");
+ }}
+ className="shrink-0 rounded-lg px-2.5 py-1.5 text-[11px] text-[var(--ink-mute)] transition-colors hover:bg-[var(--surface)] hover:text-[var(--coral)]"
+ >
+ {t("agent.customBin.clear")}
+ </button>
+ )}
+ {dirty && (
+ <button
+ onClick={() => onChange(draft)}
+ className="shrink-0 rounded-lg px-3 py-1.5 text-[11px] font-medium"
+ style={{ background: "var(--ink)", color: "var(--paper)" }}
+ >
+ {t("agent.customBin.save")}
+ </button>
+ )}
+ </div>
+ <div className="mt-2 text-[10.5px] text-[var(--ink-mute)] leading-snug">
+ {t("agent.customBin.hint")}
+ </div>
+ </div>
+ );
+}
+
function MissingCard({ agent }: { agent: AgentInfo }) {
const t = useT();
const gradient = VENDOR_GRADIENT[agent.vendor] ?? "from-[var(--ink-faint)] to-[var(--ink-mute)]";
diff --git a/src/lib/agents/detect.ts b/src/lib/agents/detect.ts
index 80eaf2aa..8e4fd773 100644
--- a/src/lib/agents/detect.ts
+++ b/src/lib/agents/detect.ts
@@ -303,7 +303,10 @@ function userToolchainDirs(): string[] {
const vp = env.VP_HOME?.trim();
if (vp) dirs.push(join(vp, "bin"));
const npmPrefix = env.NPM_CONFIG_PREFIX?.trim();
- if (npmPrefix) dirs.push(join(npmPrefix, "bin"));
+ if (npmPrefix) {
+ // npm on Windows installs CLI shims directly in <prefix>, not <prefix>/bin.
+ dirs.push(join(npmPrefix, "bin"), npmPrefix);
+ }
dirs.push(
join(home, ".local/bin"),
join(home, ".vite-plus/bin"),
@@ -317,7 +320,22 @@ function userToolchainDirs(): string[] {
join(home, ".npm-packages/bin"),
join(home, ".claude/local"),
);
- if (process.platform !== "win32") {
+ if (process.platform === "win32") {
+ // Scoop-managed Node.js drops global npm shims into the app dir directly,
+ // not under a /bin/ subdirectory. Cover the common Scoop layouts plus the
+ // default %AppData%/npm location used by the standalone Node installer.
+ const scoopRoot = env.SCOOP?.trim() || join(home, "scoop");
+ const globalScoopRoot = env.SCOOP_GLOBAL?.trim() || "C:\\ProgramData\\scoop";
+ const appData = env.APPDATA?.trim();
+ dirs.push(
+ join(scoopRoot, "shims"),
+ join(scoopRoot, "apps", "nodejs", "current"),
+ join(scoopRoot, "apps", "nodejs-lts", "current"),
+ join(globalScoopRoot, "shims"),
+ join(globalScoopRoot, "apps", "nodejs", "current"),
+ );
+ if (appData) dirs.push(join(appData, "npm"));
+ } else {
dirs.push("/opt/homebrew/bin", "/usr/local/bin");
}
return dirs;
diff --git a/src/lib/agents/invoke.ts b/src/lib/agents/invoke.ts
index 0988c4bd..6626592f 100644
--- a/src/lib/agents/invoke.ts
+++ b/src/lib/agents/invoke.ts
@@ -1,4 +1,5 @@
import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
+import { existsSync } from "node:fs";
import { resolveOnPath, resolveOpenclawAgentId, AGENTS } from "./detect";
import { buildArgv, envFor, makeParser, UnsupportedAgentProtocolError } from "./argv";
@@ -8,8 +9,60 @@ export type InvokeOpts = {
cwd?: string;
model?: string;
signal?: AbortSignal;
+ /**
+ * Absolute path to the agent binary. Wins over `process.env[envOverride]`
+ * and the PATH scan when set. Surfaced from the Settings UI for users
+ * whose CLI lives outside the heuristic toolchain dirs.
+ */
+ binOverride?: string;
};
+type BinResolution =
+ | { kind: "ok"; bin: string }
+ | { kind: "override-missing"; tried: string }
+ | { kind: "not-found" };
+
+/**
+ * Resolve the binary to spawn, in priority order:
+ * 1. `opts.binOverride` (user-set absolute path from Settings UI)
+ * 2. `process.env[def.envOverride]` (e.g. CLAUDE_BIN, OPENCLAW_BIN)
+ * 3. PATH scan over `def.bin` then `def.fallbackBins`
+ *
+ * If a `binOverride` is set but doesn't resolve, return `override-missing`
+ * (do not silently fall through) — the user picked an explicit path and
+ * deserves to see the typo / wrong path instead of mysteriously running a
+ * different binary.
+ */
+function resolveBinForAgent(
+ def: (typeof AGENTS)[number],
+ binOverride: string | undefined,
+): BinResolution {
+ const tryPath = (p: string | undefined): string | null => {
+ if (!p) return null;
+ const trimmed = p.trim();
+ if (!trimmed) return null;
+ // Absolute path → must exist; relative names → fall back to PATH scan.
+ if (/^([a-zA-Z]:[\\/]|[\\/])/.test(trimmed)) {
+ return existsSync(trimmed) ? trimmed : null;
+ }
+ return resolveOnPath(trimmed);
+ };
+ if (binOverride && binOverride.trim()) {
+ const fromOverride = tryPath(binOverride);
+ if (fromOverride) return { kind: "ok", bin: fromOverride };
+ return { kind: "override-missing", tried: binOverride.trim() };
+ }
+ if (def.envOverride) {
+ const fromEnv = tryPath(process.env[def.envOverride]);
+ if (fromEnv) return { kind: "ok", bin: fromEnv };
+ }
+ for (const c of [def.bin, ...(def.fallbackBins ?? [])]) {
+ const found = resolveOnPath(c);
+ if (found) return { kind: "ok", bin: found };
+ }
+ return { kind: "not-found" };
+}
+
export type InvokeEvent =
| { type: "start"; bin: string; argv: string[]; promptBytes: number }
| { type: "delta"; text: string }
@@ -30,17 +83,18 @@ export function invokeAgent(opts: InvokeOpts): ReadableStream<InvokeEvent> {
if (!def) {
return errorStream(`unknown agent: ${opts.agent}`);
}
- const candidates = [def.bin, ...(def.fallbackBins ?? [])];
- let bin: string | null = null;
- for (const c of candidates) {
- bin = resolveOnPath(c);
- if (bin) break;
+ const resolved = resolveBinForAgent(def, opts.binOverride);
+ if (resolved.kind === "override-missing") {
+ return errorStream(
+ `${def.label}: custom path \`${resolved.tried}\` does not exist. Update or clear it in Settings → Custom path.`,
+ );
}
- if (!bin) {
+ if (resolved.kind === "not-found") {
return errorStream(
`${def.label} (\`${def.bin}\`) is not installed or not on PATH.`,
);
}
+ const bin: string = resolved.bin;
// For openclaw we need an async detection step (resolveOpenclawAgentId)
// before buildArgv. Do all of the argv assembly inside the stream's async
@@ -108,6 +162,14 @@ export function invokeAgent(opts: InvokeOpts): ReadableStream<InvokeEvent> {
cwd: opts.cwd ?? process.cwd(),
env,
stdio: ["pipe", "pipe", "pipe"],
+ // On Windows, `spawn` cannot launch a `.cmd` / `.bat` shim (which is
+ // what npm installs for most CLI agents) without going through the
+ // shell. Without this, every agent invocation fails with
+ // EINVAL / "spawn 无效的参数". macOS/Linux use direct exec.
+ // Safety: prompt content is delivered via stdin or `--message
+ // <text>` (argv-message), not interpolated into a shell command,
+ // so this does not introduce a shell-injection vector.
+ shell: process.platform === "win32",
});
} catch (err) {
safeEnqueue({
diff --git a/src/lib/i18n.ts b/src/lib/i18n.ts
index 560ce2f0..aef67940 100644
--- a/src/lib/i18n.ts
+++ b/src/lib/i18n.ts
@@ -74,6 +74,12 @@ export interface Dict {
// Agent card
"agent.selected": string;
"agent.notInstalled": string;
+ "agent.customBin.eyebrow": string;
+ "agent.customBin.subtitle": string;
+ "agent.customBin.detected": string;
+ "agent.customBin.hint": string;
+ "agent.customBin.save": string;
+ "agent.customBin.clear": string;
"protocol.stdin": string;
"protocol.argv": string;
"protocol.argvMessage": string;
@@ -345,6 +351,13 @@ const en: Dict = {
"agent.selected": "Selected",
"agent.notInstalled": "Not installed",
+ "agent.customBin.eyebrow": "custom path",
+ "agent.customBin.subtitle": "Override the auto-detected binary for {agent}",
+ "agent.customBin.detected": "Auto-detected:",
+ "agent.customBin.hint":
+ "Set this if auto-detection picked the wrong binary (e.g. Scoop on Windows, custom installs). Leave blank to use the detected path.",
+ "agent.customBin.save": "Save",
+ "agent.customBin.clear": "Clear",
"protocol.stdin": "stdin · stream",
"protocol.argv": "positional argv",
"protocol.argvMessage": "argv · batch JSON",
@@ -615,6 +628,12 @@ const zhCN: Dict = {
"agent.selected": "SELECTED",
"agent.notInstalled": "未安装",
+ "agent.customBin.eyebrow": "自定义路径",
+ "agent.customBin.subtitle": "手动指定 {agent} 的二进制路径",
+ "agent.customBin.detected": "自动检测到:",
+ "agent.customBin.hint": "如果自动检测找错了 binary(比如 Windows Scoop / 自定义安装),在这里填绝对路径。留空走自动检测。",
+ "agent.customBin.save": "保存",
+ "agent.customBin.clear": "清除",
"protocol.stdin": "stdin · stream",
"protocol.argv": "positional argv",
"protocol.argvMessage": "argv · 整段 JSON",
diff --git a/src/lib/store.ts b/src/lib/store.ts
index 3d3454a4..8948a173 100644
--- a/src/lib/store.ts
+++ b/src/lib/store.ts
@@ -141,6 +141,12 @@ type Persisted = {
selectedAgent: string | undefined;
/** Per-agent last-picked model id. Empty / "default" means no `--model` flag. */
agentModels: Record<string, string>;
+ /**
+ * Per-agent absolute path override. Wins over PATH scan and `envOverride`
+ * when set. Used by users whose CLI lives somewhere our `userToolchainDirs`
+ * heuristic doesn't cover (Scoop on Windows, custom installs, etc.).
+ */
+ agentBinOverrides: Record<string, string>;
welcomeAck: boolean;
sidebarCollapsed: boolean;
locale: Locale;
@@ -157,6 +163,8 @@ type State = {
selectedAgent?: string;
/** Per-agent model id. "default" or absent = no --model flag. */
agentModels: Record<string, string>;
+ /** Per-agent absolute binary path override. See Persisted comment. */
+ agentBinOverrides: Record<string, string>;
welcomeAck: boolean;
sidebarCollapsed: boolean;
locale: Locale;
@@ -215,6 +223,8 @@ type State = {
setAgents: (a: AgentInfo[]) => void;
setSelectedAgent: (id?: string) => void;
setAgentModel: (agentId: string, modelId: string) => void;
+ /** Set / clear an absolute path override for one agent. Empty string clears. */
+ setAgentBinOverride: (agentId: string, path: string) => void;
setWelcomeAck: (v: boolean) => void;
setSidebarCollapsed: (v: boolean) => void;
setLocale: (l: Locale) => void;
@@ -242,6 +252,7 @@ export const useStore = create<State>()(
agents: [],
selectedAgent: undefined,
agentModels: {},
+ agentBinOverrides: {},
welcomeAck: false,
sidebarCollapsed: false,
locale: "en",
@@ -381,6 +392,13 @@ export const useStore = create<State>()(
setSelectedAgent: (id) => set({ selectedAgent: id }),
setAgentModel: (agentId, modelId) =>
set((s) => ({ agentModels: { ...s.agentModels, [agentId]: modelId } })),
+ setAgentBinOverride: (agentId, path) =>
+ set((s) => {
+ const next = { ...s.agentBinOverrides };
+ if (path.trim()) next[agentId] = path.trim();
+ else delete next[agentId];
+ return { agentBinOverrides: next };
+ }),
setWelcomeAck: (v) => set({ welcomeAck: v }),
setSidebarCollapsed: (v) => set({ sidebarCollapsed: v }),
setLocale: (l) => set({ locale: l }),
@@ -390,7 +408,7 @@ export const useStore = create<State>()(
// Legacy key from the old "HTML Everything" brand; do NOT rename — every
// existing user's saved tasks live under this localStorage key.
name: "html-everything-store",
- version: 5,
+ version: 6,
partialize: (s): Persisted => ({
tasks: s.tasks.map((t) => ({
...t,
@@ -400,6 +418,7 @@ export const useStore = create<State>()(
activeTaskId: s.activeTaskId,
selectedAgent: s.selectedAgent,
agentModels: s.agentModels,
+ agentBinOverrides: s.agentBinOverrides,
welcomeAck: s.welcomeAck,
sidebarCollapsed: s.sidebarCollapsed,
locale: s.locale,
@@ -449,6 +468,13 @@ export const useStore = create<State>()(
p.layoutMode = "split";
}
}
+ // v5 → v6: introduce agentBinOverrides map.
+ if (fromVersion < 6 && persisted && typeof persisted === "object") {
+ const p = persisted as Record<string, unknown>;
+ if (!p.agentBinOverrides || typeof p.agentBinOverrides !== "object") {
+ p.agentBinOverrides = {};
+ }
+ }
return persisted as Persisted;
},
},
diff --git a/src/lib/use-convert.ts b/src/lib/use-convert.ts
index d911d02e..17306c5a 100644
--- a/src/lib/use-convert.ts
+++ b/src/lib/use-convert.ts
@@ -60,6 +60,7 @@ export function useConvert() {
: summary.raw;
const useModel = req.model && req.model !== "default" ? req.model : undefined;
+ const binOverride = store.agentBinOverrides[req.agent]?.trim() || undefined;
// diff-edit mode: if the task was loaded from a sample (or the user has
// already converted once) AND the content has actually changed, we ship
@@ -84,6 +85,7 @@ export function useConvert() {
content: enrichedContent,
format: req.format ?? summary.format,
...(useModel ? { model: useModel } : {}),
+ ...(binOverride ? { binOverride } : {}),
...(editPayload ?? {}),
};
diff --git a/src/lib/use-draft.ts b/src/lib/use-draft.ts
index 0482ae1d..510264c9 100644
--- a/src/lib/use-draft.ts
+++ b/src/lib/use-draft.ts
@@ -46,6 +46,7 @@ export function useDraft() {
agentModels[agent] && agentModels[agent] !== "default"
? agentModels[agent]
: undefined;
+ const binOverride = store.agentBinOverrides[agent]?.trim() || undefined;
const ctl = new AbortController();
ctlRef.current = ctl;
@@ -69,6 +70,7 @@ export function useDraft() {
instruction: req.instruction,
context: req.context ?? before,
...(model ? { model } : {}),
+ ...(binOverride ? { binOverride } : {}),
}),
signal: ctl.signal,
});