Magent Frontend Boundary

The agent-shell integration is the complete conversational interface. Magent does not maintain a parallel workspace, compose buffer, command menu, or custom output-buffer frontend. New conversational behavior belongs in agent-shell or in the ACP adapter; shared runtime behavior belongs in the runtime API, while explicit command registration and invocation belong in magent-action.el.

• magent-agent-shell.el supplies the Magent agent-shell configuration, the compatibility entry magent-start, and an isolated context compatibility block. Interactive buffer and prompt behavior remains owned by agent-shell.
• magent-acp.el implements the in-process ACP request, notification, response, permission, and session/update adapter.
• magent-action.el owns registered slash/interactive command discovery and the invocation lifecycle; magent-action-session.el adds isolated durable persistence without becoming a frontend.
• magent-runtime-api.el is the frontend-neutral runtime and session API.
• magent-runtime-queue.el owns per-session FIFO execution and session-scoped cancellation; independent sessions run concurrently, even in one project.

1. Start Magent with M-x magent-start, or register Magent with magent-agent-shell-ensure-config and select it from M-x agent-shell.
2. agent-shell calls the in-process ACP client from magent-acp.el.
3. ACP normalizes text and resource blocks separately. Local file:// resources populate scoped request paths, while resource bodies remain user-role context when history is reconstructed.
4. ACP resolves registered slash input against the runtime session’s exact scope and invokes it through magent-action.el. Ordinary prompts go directly to magent-runtime-api.el. Command-owned turns and workflow steps also use that API; direct handlers may complete without a general agent turn.
5. The runtime API freezes one magent-request-context with :ui-visibility 'none before queueing. The queue starts exactly one active turn at a time and passes that context unchanged to magent-agent-run-turn.
6. The agent loop emits Magent-native observer events; magent-acp.el converts them to ACP session/update messages for agent-shell.
7. ACP prompt requests remain pending until the corresponding ordinary turn or command invocation completes, fails, or is cancelled.

• magent-agent-shell-session-strategy selects the supported frontend’s new, latest, or prompt-based session flow for both the Magent entry command and Magent selected from the generic agent-shell picker. It defaults to prompt, offering new and saved sessions from the current scope.
• ACP exposes one native model session option containing every model from every backend registered with gptel. Display names use provider:model; opaque ids keep same-named models from different providers distinct. Selecting a model stores a session-local route without mutating gptel’s global backend or model variables. Auto clears that route and displays the currently resolved agent/default model.

Model routing is resolved and frozen when a runtime submission is created. The precedence for a user-facing turn is session route, explicit agent model, then gptel defaults. A child agent instead prefers its own explicit model over the frozen parent route and otherwise inherits the parent. The route object also retains agent-profile and phase fields as an API seam for future per-agent or per-phase policy; there is no phase router in the current runtime. Switching the session model affects only later submissions, not active work, already queued work, or a provider-native tool continuation.

Magent implements ACP session/new, session/list, session/load, session/resume, and session/fork. agent-shell-fork creates a new durable session with an independent ledger and the source conversation as its initial history. The source and fork retain separate ids and diverge after creation.

Forking is exact-scope and fail-closed: the requested cwd must resolve to the source session’s scope, and the source must have no active or queued work. Stable frontend options such as the selected agent, model route, effort, thinking mode, and automatic capability setting are inherited. Session approval overrides, child-agent jobs, and one-shot skills are deliberately reset. Referenced spilled tool outputs are copied into the fork’s private session storage.

Keep frontend-neutral behavior in magent-runtime-api.el, ACP conversion in magent-acp.el, and interactive frontend behavior in agent-shell. Keep magent-agent-shell.el limited to Magent’s config and the explicitly grouped context compatibility advices. Do not introduce a second interactive frontend inside the core runtime.

Skill discovery is also frontend-neutral. magent-skills-list-descriptors and magent-skills-resolve-descriptor return metadata for an exact session scope without exposing prompt bodies or executable handlers. ACP flattens instruction skills into its command list as $name because agent-shell has one slash-menu surface, then dispatches /$name as an ordinary magent-runtime-submit :skills turn. A future frontend may instead present registered Action command projections and skill descriptors as two separate entry surfaces; it must not infer skills from the Action registry.

• agent-shell and acp are hard dependencies of the supported frontend.
• Magent still explicitly registers its config for the generic agent-shell picker, and temporarily advises four private context functions for remote-safe and blank-line context handling.
• Runtime execution is serial within each session and concurrent across sessions, including sessions in the same project. Completion and cancellation address exact submissions; a busy or approval-waiting session does not block peers.
• Cancellation is session-scoped: cancelling one ACP session cancels that session’s active and queued submissions without interrupting other sessions’ active or queued work.
• Per-request instruction skill overrides, scope-aware /$skill projection, and Elisp-native Action command projections are supported. Per-request agent overrides are not currently exposed by the supported frontend.
• ACP session config exposes Automatic capabilities. Disabling it suppresses contextual capability auto-resolution for future turns in that session while retaining explicitly selected instruction skills.
• Model routes are session-local in memory. Cross-Emacs persistence of an explicit route is not yet implemented; a loaded session returns to Auto.
• Forking an active turn and forking across project scopes are not supported.

Ordered assistant message items preserve progress/tool/final boundaries on resume. Reasoning visibility remains independent of assistant communication. The runtime’s plan-update event carries ACP-shaped entries; magent-acp.el projects it to a native plan update. Persisted plan items replay through the same path, so agent-shell owns the plan display. Cancelled or failed tools are shown as failed on replay rather than receiving a successful completion icon. Empty final answers from ordinary agent turns fail the pending prompt with an explicit diagnostic; no hidden answer-recovery request is sent.