Module app_api 

App API — high-level commands for programmatic control of AgentMux.

These commands orchestrate multiple low-level operations (CreateBlock, SetMeta, ControllerResync) behind stable, intent-based interfaces. Callers express what they want (“open an agent pane with AgentX”), not how to do it.

Functions

agent_define_core 🔒

allocate_agent_workdir

Atomically allocate an agent working directory.

build_pane_meta 🔒

Build the metadata map for a pane.open request, validating required args.

extract_digest_text 🔒

Extract meaningful text from raw stream-json lines for digest summarization. Skips system/result events and raw stream_event deltas; extracts assistant text and tool call summaries.

find_agent_block 🔒

Find an existing agent block in a tab by agent ID.

global_output_source 🔒

If this channel has no local output for block_id but the agent’s GLOBAL transcript zone (agent:<defId>:current) does, return (global_store, agent_zone). Returns None when the local output is present and non-empty, the block isn’t agent-anchored, there’s no global store, or the global zone is empty — callers then read the per-channel store keyed by block_id.

global_zone_line_count 🔒

Exact non-blank line count of the output file in zone, computed via the same streaming index builder read_range uses (so the two endpoints always agree). Returns Some(0) for an empty file, None on read failure.

infer_provider_from_model 🔒

Create a stub AgentInstance for a definition, idempotently.

invoke_cli_for_activity 🔒

Invoke the Claude CLI with Haiku model for a lightweight per-turn activity summary. Uses --model claude-haiku-4-5-20251001 and a 15s timeout.

invoke_cli_for_digest 🔒

Invoke the Claude CLI with a prompt and extract the text response. Uses -p --output-format stream-json --verbose (non-interactive mode).

make_stub_idempotent 🔒

Returns (stub_id, newly_inserted). newly_inserted = false when the UNIQUE constraint fires (stub already existed); callers use this to avoid broadcasting agents:changed on no-op calls.

open_pane

Core pane.open logic, shared by the WebSocket RPC handler (register_pane_open) and the HTTP route POST /api/v1/pane/open (agentmux-mcp’s OpenEditor tool). Creates a block for the requested view, enqueues a layout action (split or insert), and broadcasts the block/tab/layout updates so the frontend renders the new pane.

open_pane_floating 🔒

Floating-pane branch of open_pane. The block already exists in source_tab_id’s blockids (created by the caller, with no layout node). This moves it into a fresh floating workspace via the tear_off_block saga, sets up the new tab’s layout, broadcasts the new WaveObjs, and asks the source window’s frontend to materialize the chromeless floating OS window via the host open_floating_pane_window command (srv cannot open windows itself). See docs/specs/SPEC_OPENEDITOR_FLOATING_AND_COLLAPSED_TREE_2026_06_16.md.

parse_seed_zoom 🔒

Parse + validate a saved per-agent ui:zoom content blob for seeding a new agent block’s term:zoom. Returns Some(z) only for a parseable, non-default (≠ 1.0), in-[0.5, 2.0] zoom (the range the frontend enforces in term.tsx); anything else (default, out of range, garbage) returns None so the new block opens at the default 1.0. See SPEC_AGENT_ZOOM_PERSISTENCE §4.2.

persist_define_content 🔒

Core logic for the agent.define command, shared by the WebSocket RPC handler and the HTTP service dispatch (("agent", "define") in service.rs). Persist system_prompt and env content blobs for a freshly created or updated agent definition. Errors are logged but not propagated — the definition row is already committed and the caller has already published agents:changed, so a content-write failure must not abort the response.

register_agent_define 🔒

register_agent_kill_process 🔒

register_agent_kill_tree 🔒

register_agent_list 🔒

register_agent_open 🔒

register_agent_output 🔒

register_agent_process_list 🔒

register_agent_send 🔒

register_agent_status 🔒

register_agent_stop 🔒

register_agent_tracked_blocks 🔒

register_app_api_handlers

Register all App API handlers on the RPC engine.

register_blockfile_line_count 🔒

register_blockfile_read_range 🔒

register_blockfile_read_state 🔒

register_blockfile_write_state 🔒

register_pane_open 🔒

register_session_activity_summary 🔒

register_session_archive_handler 🔒

register_session_digest 🔒

register_session_export_handler 🔒

register_session_restore_handler 🔒

resolve_placement 🔒

Translate split_direction + split_reference_block_id into the backend layout action triple. Returns (actiontype, targetblockid, position). Falls back to a plain insert if direction/reference are missing.

resolve_tab_id 🔒

Resolve a tab ID: use the provided one, or fall back to the first workspace’s active tab.

write_agent_config_files 🔒

Write agent config files (CLAUDE.md, .mcp.json, etc.) to the working directory.