Macros and Scripts

Macros and scripts automate explicit tasks. They remain subject to the same permissions, confirmations and audit requirements as other app actions.

Macros

Use a macro for a named sequence you expect to reuse:

• save_macro, list_macros and show_macros manage your library.
• view_macro_code lets you review a macro before running it.
• run_macro or run_saved_macro runs a supported sequence.
• delete_macro removes a saved macro.

The native macro library, authenticated Web Command Center and desktop TUI use the same saved macros. TUI shortcuts include /macros, /macro-save <name> <script>, /macro-run <id|name> and /macro-delete <id|name>.

When a nested action requires approval, the macro waits for that action's normal review. Saving or starting a macro does not grant blanket permission for its future actions.

Agent-authored scripts

run_agent_script runs a one-off helper script. Available modes depend on the host:

Mode	Purpose
QuickJS	Supported sandboxed macro logic
python_mini	Small deterministic scripts that produce JSON
python	Allowed tool calls through telemus_tools.tools.call()
python_external or bash	Explicit filesystem or process work on a supported desktop host

Embedded scripts do not automatically receive filesystem, process, network or credential access. For Python tool calling, use tool_allowlist to choose allowed tools; an empty list denies all tools. Unsupported execution modes report that they are unavailable. Android/Quest and browser-only builds do not provide the desktop local-process host.

ACP control

agent_acp_control inspects availability or sends a prompt to a supported ACP agent. ACP is separate from interactive terminal control. Check status before selecting a profile: configured support is not proof that an agent is running.

Use the app's supported ACP controls, Web status or terminal /acp command for runtime availability. Starting an external agent follows the normal permission and confirmation requirements.

Execution backends

agent_execution_backend supports status, a dry-run plan and explicit execution on configured backends. Local, Docker, SSH, remote-agent, Daytona and Modal availability depends on the host and its configuration. A listed backend may still need credentials or software installed by the operator.

Use shell_exec for command execution and process to inspect or manage a returned background session. A normal exit code is separate from whether the command achieved the requested result; read its output and errors.

A yielded command can continue running after the assistant responds. Use the returned session ID to poll, read logs, send supported stdin or stop the owned job. Do not start a duplicate command merely because the first has not finished. Cancellation cannot guarantee that every detached child process has exited.

Output, waits and timeouts

A startup wait and a command timeout are different. yieldMs controls how long a supported foreground call waits before returning a background session. Use timeout_ms for the command's allowed duration, within the operator's limits. A poll or wait does not extend that duration.

Large output is truncated with a visible notice. Use process log paging to inspect retained output. A poll can return only new output; no new output does not mean the process stopped. Follow the reported polling guidance.

For file reads, use read_file with a smaller limit and a 1-based offset when results are too large. Follow next_offset when present. Process-log paging uses a 0-based offset. Truncated output is not a complete record of the operation.

Structured file edits

edit accepts path and edits: [{oldText, newText}]. Replacements must match unique, nonoverlapping regions of the original file. A missing, ambiguous or conflicting match fails without changing the file. Use an empty newText to delete a matched region.

Read the current text before editing. The structured edit mode uses exact text matching with newline normalization; it does not guess which similar passage you meant. File permissions, approvals and workspace restrictions still apply.

Images and vision

On supported vision-capable provider/model routes, read_file can supply an eligible PNG as image input. Unsupported formats or routes return an omission or conversion note. Large images must be reduced before use; current limits are 1 MiB per PNG, 1200 pixels per axis and four images per run.

The selected model provider receives images you submit. Local handling does not override that provider's retention policy. Text-only routes do not gain vision by receiving a file path.

Choose the right tool

• Use a macro for a repeatable named sequence.
• Use run_agent_script for a short, supported helper task.
• Use shell_exec and process for explicit command work and background sessions.
• Use agent_execution_backend when you need a configured execution destination.
• Use agent_acp_control to work with a supported external ACP agent.
• Use a plugin for a packaged capability you can inspect, enable and reuse.

These shared controls apply across native 3D, Web and TUI where the required host is available. See Plugins and Extensions and Command Reference.