mcpx: exec should run any shebang, and resolve file scripts the same way local or remote #1919

Relocated from dezren39/darwin-nix#106 on 2026-10-28 (placement audit): mcpx's single source lives in developing-today/code (pkgs/mcpx); re-home tracked at #309. Original body below; issue references inside it are historical (dezren39/nix numbering).

Parent: #175

Summary

Two limits on what mcpx exec and mcpx run will accept. First, they run
TypeScript and nothing else: there is no way to run a shell script, a Python
one-liner, or anything with a shebang, on any surface. Second, /v1/exec
accepts a file field but resolves it as a raw path on the daemon's
filesystem, while the CLI resolves a script name against a search path — so a
named script is a local-only concept and the two sides disagree about what a
"file" is.

Original notes

• can exec call bash across the modes?
  • nearly just allow any shebang
    • drop the user in <user_config>||||pwd
    • if not shebang or --shell||--bash||--shell python3||--#!/usr/bin/python
    • then configured typescript
  • ./mcpx -exec
• any exec local or remote should allow file scripts, server looks where it finds scripts and tries to find, same as local.

Current state

Nothing runs but TypeScript

runner.Detect returns one of three JavaScript runtimes and runner.Run
spawns it. There is no shell, no interpreter selection, no shebang handling
anywhere — rg -n "shebang|#!|--shell" across internal/cli and
internal/adapter finds only mcpx completion bash.

The nearest existing thing is script.launcher = none (runner.LauncherNone,
internal/runner/runner.go:493-497), documented as "the escape hatch for a
script that wants the runtime and none of the harness". Since #75 it, and
--launcher/--no-launcher/--export/--allow-repeat/--no-capture-console,
apply to exec snippets as well as run files (#74 closed). It removes mcpx's
shim; it does not change the interpreter.

Related but different: paths.adapters wraps an existing CLI as an MCP
server, so a shell tool can be reached from a script. That is "call out to a
command", not "this script is a shell script".

file means two different things

• CLI, local: resolveScript(arg) (internal/cli/scripts.go) — an argument
  that looks like a path is used verbatim; otherwise the name is looked up on
  the script search path (every .config/mcpx/scripts and .mcpx/scripts from
  the working directory up, then the user directory, with paths.scripts and
  the null splice), trying .ts, .mts, .js, .mjs. A miss produces a
  good error listing every directory searched and the mkdir to fix it.
• CLI, remote: execOnDaemon (internal/cli/exec.go:448) calls
  resolveScript locally, reads the file, and sends its text. So a named
  script works remotely — by being resolved here and shipped as source.
  --export is refused with an explicit message because it needs a module on
  the runtime's disk (exec.go:453-458; only for files — on an inline snippet
  --export is not refused and not sent). The other exec flags are not refused,
  they are dropped: runScript hands off to execOnDaemon (internal/cli/commands.go:556-559)
  before --launcher, --no-launcher, the phase flags, --typecheck, --env,
  --no-capture-console and --allow-repeat are read (:573-843), and
  execsvc.Options has no field for most of them (internal/execsvc/execsvc.go:101-124).
  Update Rust crate proc-macro2 to 1.0.81 - autoclosed #75 closed that class for the local path only. Part 4 below moves resolution
  to the daemon; it should carry these flags on the wire or refuse them, as it
  already refuses --export.
• /v1/exec and MCP: execReq.File (internal/daemon/routes_exec.go) is
  passed through execsvc.Request{File: …} into runner.Options.File
  (internal/execsvc/execsvc.go:327), and the runner does filepath.Abs and
  runs it (internal/runner/runner.go:293).
  No search path, no name resolution, no error naming where it looked. A
  caller that is not the mcpx CLI — the opencode plugin, a remote agent, an MCP
  client — can therefore only name absolute or cwd-relative paths on the
  daemon's machine.

docs/exec.md says "A remote run sends the script's text, not its path",
which is true of the CLI and not true of the endpoint. That is the gap the
user's second bullet names.

Approaches

Approach A — least recommended: a --shell/--bash flag pair on exec

Add --shell, --bash, --python flags that swap the interpreter.

Why not: it is a fixed list that will never be the right fixed list — the user's
own note already escalates from --shell to --bash to --shell python3 to
--#!/usr/bin/python within one line, which is the flag set discovering it
wants to be a string. Every addition is a new flag on two commands, a new
ExecOptions field and a new MCP tool parameter. The project has a settings
registry precisely so that one declaration reaches every surface; a flag family
bypasses it. It also leaves the file-resolution half of this issue untouched.

Approach B — middle: an script.interpreter setting plus shebang detection

One setting, script.interpreter, whose value is a command line: empty means
"use the configured language/runtime", anything else is argv the script path is
appended to (bash, python3 -u, /usr/bin/env -S deno run -A). Plus: if the
source or file begins with #!, honour it — on a file by making it executable
and running it directly, on a snippet by writing it to a temporary file with
the shebang intact.

--shell and --bash become aliases for script.interpreter=sh and =bash if
they are wanted at all, which keeps the user's spelling available without the
combinatorics. KindString already exists; FlagAliases already exists; the
value reaches CLI, env, config, /v1/settings and MCP for free.

This answers "can exec call bash across the modes?" — yes, everywhere, because
it is a setting and settings are already everywhere. It stops short of two
things: it does not say what the working directory should be (the user's
"drop the user in <user_config>||<config>||pwd"), and it has no story for what
the harness means when there is no TypeScript client — a bash script gets no
tools, no emit, no artifact, and mcpx becomes a slower bash -c.

Approach C — recommended: shebang-first dispatch, with the harness offered rather than assumed, and one script-resolution rule for every surface

Three parts.

1. Dispatch order. Exactly the order the user wrote, made explicit:

Unset defaults mean nothing changes for anyone. A shebang is self-describing,
travels with the script text, and therefore works identically for a local run, a
remote exec and a named script — which is the property that makes it the right
primary rule rather than a flag.

2. The harness is opt-in per interpreter, and its absence is stated. A
non-JS interpreter gets, at minimum: MCPX_ENDPOINT, MCPX_SESSION,
MCPX_SOCKET, MCPX_RUNTIME and the script's args in the environment, so a
bash script can curl the daemon; and stdout/stderr/exit code handled by
the same execsvc machinery, so frames, logs, artifacts-by-reference and
timeouts work unchanged. What it does not get is the generated client, and mcpx
should say so once rather than let the author discover it. This is the same
posture runner.Permissions takes about bun and node having no sandbox, and
preflight.TypeCheck takes about type checking — state the limitation, do not
pretend.

A shell script that can reach $MCPX_ENDPOINT with curl is genuinely useful
and costs almost nothing to enable, because the daemon already binds a
loopback HTTP endpoint for exactly this reason (a unix socket is not portable
across runtimes — docs/dependencies.md).

3. Working directory becomes a named policy, not an accident. The user's
<user_config>||<config>||pwd is asking for a rule. Propose script.cwd with
values caller | script | config | workdir:

• caller (default) — today's behaviour and runner.Run's stated intent: "a
  relative path in a script should mean what it means on the command line".
• script — the directory the script file lives in, which is what a named
  script in .config/mcpx/scripts usually wants.
• config — the nearest mcpx config directory, the user's <config>.
• workdir — the content-addressed exec workdir, i.e. isolated.

This matters more once shebangs exist, because a shell script's relative paths
are far more load-bearing than a TypeScript one's, and ExecOptions.cwd already
crosses the wire so the remote case has somewhere to put the answer.

4. One resolution rule, both sides. Move resolveScript out of
internal/cli into a package internal/execsvc can call, and have the daemon
resolve file the same way — search path, null splice, extension list, and
the same error that names every directory it looked in. Then:

• POST /v1/exec {"file": "report"} finds report.ts on the daemon's search
  path, which is what the user's bullet asks for and what the opencode plugin
  needs (Update Rust crate anyhow to 1.0.75 #48; since chore(deps): bump build/buck/preludes/buck2-prelude from d956689 to 880be56 #53 closed Bump rustls-webpki from 0.100.1 to 0.100.2 in /sources/pavex/examples/realworld #44 the plugin reaches the daemon over its socket
  without the binary, so it cannot resolve a name locally the way the CLI does).
• The CLI's existing behaviour — resolve locally, send text — stays the default
  for --remote, because mcpx run ./report.ts --remote means the file in
  front of you. A new --remote-file/file: form asks the daemon to resolve
  instead. The two are genuinely different requests and both are wanted.
• --export becomes possible on a remote run when the daemon resolved the file
  itself, since there is then a module on the runtime's disk. That removes one
  of the two refusals docs/exec.md lists under "Not done".

On ./mcpx -exec: the most useful reading is mcpx as a shebang interpreter —
#!/usr/bin/env -S mcpx run at the top of a .ts file, making a script
directly executable while still getting the client, the launcher and the tool
namespaces. It should be listed as done-when.

Corrected 2026-09-30 (this paragraph said mcpx exec and called it a two-line
change):

• The interpreter must be mcpx run, not mcpx exec. The kernel appends the
  file's path, and exec takes source text, so mcpx exec ./x.ts would run the
  string ./x.ts as TypeScript.
• With run it probably works already. A file script is imported unchanged by
  the launcher (runner.go:292-310), and all three runtimes skip a line-1
  hashbang in an imported module. Verified here with deno 2.9.6, bun 1.3.11 and
  node 24.20.0: a module starting #!/usr/bin/env -S mcpx run, imported by
  another, loads and runs. Not yet verified end to end through mcpx. The work is
  a test, not a feature.
• A snippet starting with #! does fail under exec. The prelude is prepended
  (runner.go:282), and a hashbang is only legal on line 1 (a #! on line 2 is
  a syntax error on all three). That is part 1's snippet case, not this one.

Open questions

• Does a shebang override script.runtime silently, or warn when both are
  specified and disagree? Silently winning is the usual Unix rule; a warning is
  more in keeping with this project's habits.
• Shebang on a snippet: mcpx exec '#!/bin/bash\necho hi' must be written to
  a file to run. Where — the content-addressed exec workdir, subject to the same
  pruning? And does it get the +x bit, or is the interpreter parsed out and
  invoked directly (safer, and works where the workdir is noexec)?
• script.permissions is meaningless for a shell script. Warn, ignore, or
  refuse when a non-default permission profile is set?
• Should the daemon's script search path be the same setting as the CLI's
  (paths.scripts) with its own scope, or a distinct paths.daemonScripts? A
  daemon resolving names from the invoking user's home directory is a different
  thing from resolving them from its own.
• Does internal/diagnose's static tool-call scan simply not run for non-JS
  interpreters, or does it report "not analysable for this interpreter"?
• Does a shebang'd script still get --typecheck? Under Approach C's
  script.check, onUnsupported already has the vocabulary for this.

Ease · Impact · Related

Ease M (dispatch and cwd policy) / L (shared script resolution across CLI and
daemon) · Impact high — it turns exec from "run TypeScript" into "run a
script", and it closes a real CLI-vs-/v1 divergence of the kind #76 tracks.

Depends on / related: #76 (CLI ↔ /v1 parity), #48 (harness-free plugin
core; a plugin with no binary is the caller that needs daemon-side
resolution), #44 (closed, fixed in #53 — the plugin no longer needs the
binary), #75 (merged: exec honours its flags locally; the remote path is still
open, above), #5 (paths.config, the config-directory chain script.cwd=config
would follow), #40 (closed, fixed in #57 — ExecOptions), #7 (launcher, which a
non-JS interpreter bypasses), and siblings #100 (runtime selection;
script.checkOnUnsupported), #105 (Python parity; dispatch rank 3) and #107
(flake execution environments; exec.env composes on the interpreter seam).

Security/auth deferred; see tracker.