Skip to content

feat(agent): install the maple-agent command from General settings - #1436

Open
w3irdrobot wants to merge 3 commits into
masterfrom
feat/agent-cli-launcher
Open

w3irdrobot wants to merge 3 commits into
masterfrom
feat/agent-cli-launcher

Conversation

@w3irdrobot

@w3irdrobot w3irdrobot commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Adds Settings > General > Command line, which installs a maple-agent command so terminals and ACP clients (Zed, Paseo, …) can run maple-agent acp without knowing where the app is installed. This prepares Maple for ACP agent catalogs that launch a fixed command, such as Paseo's.

  • Where it installs:
    • macOS: /usr/local/bin, which is on the default PATH. When that folder isn't writable or doesn't exist, the privileged step goes through macOS's own administrator prompt (osascript … with administrator privileges).
    • Linux: ~/.local/bin, the same place the Linux installer already puts its wrapper.
  • Launcher, not a copy or symlink. The command is a marked script, #!/bin/sh + # maple-agent-cli-launcher-v1 + exec '<installed app>' "$@". Updates replace the app in place (macOS swaps the bundle at the same path), so the launcher stays current. current_exe() stays inside the bundle, which matters for self-launch and notification checks. A symlink would make macOS report the symlink's path instead.
  • Ownership. Maple only rewrites or removes a regular file with its own marker. A symlink, a folder, or any other file at that path is reported and left untouched. The Linux installer's wrapper (maple-agent-user-install-v1) counts as installed and is never modified.
  • The privileged step is a single sh command line built only from single-quoted arguments: each launcher line is a separate printf argument, then a staged file, chmod 0755 and mv. AppleScript gets no newlines. Install runs as a create that refuses a file appearing after the unprivileged check. Remove uses the same prompt when needed. Cancelling the prompt reports that nothing changed.
  • States and actions:
    • Missing → Install
    • Our launcher points at another copy → Update (atomic replace)
    • Ours and current → Remove
    • Foreign file, or installed by the Linux installer → explanation only, no button
  • PATH check. When installed, the row reuses the login-shell PATH probe (login_search_path, now exported from the runtime crate) and says if the folder is not on the shell's PATH.
  • Availability.
    • Installed (packaged) builds only.
    • macOS refuses a bundle still on its disk image or app-translocated.
    • Flatpak is refused.
    • Dev installs use maple-agent-dev, matching the Linux installer.
    • Unpackaged builds show why the button isn't offered, unless MAPLE_CLI_LAUNCHER_TARGET names an executable. That variable exists so the row can be exercised against a Local stack. Packaged builds ignore it.
  • Windows is out of scope here. Windows gets no launcher script. The installed root %LOCALAPPDATA%\Programs\Maple Work\maple-agent.exe is already a stable bootstrap: given arguments, it starts the selected version, passes argv and stdio through, waits, and returns the exit code (windows_bootstrap.rs). The Windows piece is adding that folder to the user PATH from the installer and removing it on uninstall. A .cmd shim would also break Node-based clients, which can't spawn .cmd without a shell. The row explains this on Windows for now.
  • Vim navigation: the button is a General target only while it has an action.

Validation

All runs were in an isolated MDE workspace (cli-path) on Linux x86_64, inside the Agent's pinned Nix shell.

GUI, Local lane (screenshots are in a PR comment):

  • Stack: MDE Local stack (OpenSecret, Postgres, Continuum, local billing) with the agent-pro Local fixture account.
  • App: the exact debug build (maple-agent 0.0.16 (dd2c4c81-dirty), i.e. this branch before the second commit's docs-only change) on Xvfb + xfwm4, driven by Cua Driver 0.38.0.
  • Setup: HOME was a temporary folder whose login profile adds ~/.local/bin to PATH. MAPLE_CLI_LAUNCHER_TARGET pointed at the debug binary.

Steps:

  1. Signed in against http://127.0.0.1:31127, then opened Settings > General. The Command line row showed Install.
  2. Install wrote ~/.local/bin/maple-agent with mode 755 and the expected marked script. The row switched to "maple-agent runs this app from ~/.local/bin/maple-agent…" with Remove, which also shows the login-shell PATH check found the folder. Running the new command printed maple-agent 0.0.16 (dd2c4c81-dirty).
  3. Remove deleted the file.
  4. A hand-written foreign file at that path was reported as "not created by Maple Work" with no button, and its contents were unchanged.
  5. Quit (Ctrl+Q) exited cleanly. All workspace services were stopped afterwards.

Automated:

  • Launcher tests: cargo test -p maple-agent-app -- cli_launcher command_line, 12 tests, all pass:
    • running the generated launcher (argv and stdio pass through, including a path containing a quote)
    • running the privileged command through sh against a temp folder (one line, mode 755, the create guard refusing a late file, update in place, no staged leftovers)
    • AppleScript escaping, ownership rules, the Linux installer wrapper, macOS bundle-path rules, and PATH matching
  • First commit:
    • just ci-lint passed.
    • just ci-test: 2,007 passed and 2 failed. Both failures were system_theme_helper timeouts under full-run load; on their own they pass in 0.25s.
  • Second commit: cargo fmt, app clippy (-D warnings), the focused tests and just build passed. The full gates were not rerun.

Not verified:

  • macOS: the administrator prompt and /usr/local/bin were not exercised on a Mac. The privileged command was tested via sh on Linux.
  • Packaged builds: none were tested.
  • CI: agent-lint, agent-test, agent-macos, agent-windows and ci-ok all pass on 084f653b. agent-windows first caught launcher states that are dead code on Windows; the third commit fixes that.

🤖 Generated with Claude Code

w3irdrobot and others added 3 commits November 3, 2026 05:02
Settings > General > Command line writes a marked launcher script to
~/.local/bin that execs the installed app, so terminals and ACP clients
can run `maple-agent acp`. A script keeps updates and current_exe()
unchanged; only files carrying Maple's marker are replaced or removed,
and the Linux installer's wrapper counts as installed. The row says when
~/.local/bin is not on the login shell's PATH. Windows is not covered yet.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
macOS writes the launcher to /usr/local/bin, which is on the default
PATH, through the system administrator prompt when that folder is not
writable. The privileged step is one sh command built from quoted
arguments; a create refuses a file that appeared after the check.
Unpackaged builds can set MAPLE_CLI_LAUNCHER_TARGET to exercise the row.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@w3irdrobot

Copy link
Copy Markdown
Contributor Author

GUI check of Settings > General > Command line (Local lane, debug build on Xvfb, temporary HOME with ~/.local/bin on the login PATH):

  1. Install offered
  2. After Install: launcher written; row shows Remove and finds the folder on the shell's PATH
  3. With a file Maple didn't write at that path: reported, no button, file left unchanged

Command line row: Install, installed, foreign file

Full General pane after Install

Settings > General after Install

@w3irdrobot
w3irdrobot marked this pull request as ready for review November 3, 2026 16:35
@w3irdrobot

w3irdrobot commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor Author

@AnthonyRonning this seems to be fine on linux since the binary ends up in the path already in our install. can you test this on Mac? and i'm not sure how to test windows haha

@AnthonyRonning

AnthonyRonning commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

I want to think about this a lot more and revisit all the threads and approaches that I went with for the daemon design to begin with, I spent a lot of time on the design and I can't remember exactly how it is and how something like this might change things. And also things like updates.

@w3irdrobot

Copy link
Copy Markdown
Contributor Author

That's fine. This isn't something we need unless we want to more easily integrate ourselves with other harnesses. The idea is to get us on the command path on the OS. So if there's another approach that's better, that's fine with me as well.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants