Commands And Action Workflows

Uses the hidden, tool-free compaction agent to produce a continuation summary. After it succeeds, future turns reuse that summary instead of the older model context. The visible transcript remains available in the current agent-shell buffer. A failed compaction leaves the previous context unchanged.

This is a chat-only Action: invoke /authority in agent-shell. It is not offered by M-x magent-action.

Returns the effective catalog view for the current session agent. Each row shows the permission key, final decision, whether the tool is exposed, the rule or session-override source, resource sub-rules, approval policy, and whether execution happens in the host, a child Emacs, or the live Emacs.

Inspects the relevant buffer, region, file, diff, error, or project context and explains the entry points, data flow, state changes, and ownership boundaries. It is intended for understanding existing behavior and does not make edits.

/explain why this callback can complete twice

Reconstructs the symptom, identifies the smallest plausible root cause, makes a focused change, adds or updates a regression test when practical, and runs the verification that should catch the problem.

/fix reproduce and repair the failing ledger replay test

Inspects repository documentation, manifests, tests, and workflows, then creates or refreshes the project-root AGENTS.md. Useful existing instructions are preserved and unrelated churn should be avoided.

/init include the live Emacs verification workflow

Reviews the current repository state and diff like a senior code reviewer. It prioritizes correctness bugs, regressions, unsafe edge cases, and missing tests, with findings ordered by severity. It does not edit files unless explicitly asked.

/review focus on cancellation and stale callbacks

Finds the relevant project test command, starts with the narrowest meaningful test, and broadens only when useful. The result records passed, failed, and skipped checks plus remaining risk.

/test run the focused tests for the files changed in this branch

agent-shell advertises registered slash commands and runs the selected /name input. The bundled one-turn prompt Actions are data entries in magent-action-builtins.el; third-party packages use the same public Action API:

(require 'magent-action)

(defun my-magent-review-buffer-p (buffer)
  "Return non-nil when BUFFER contains a reviewable diff."
  (with-current-buffer buffer
    (derived-mode-p 'diff-mode)))

(magent-define-workflow my-magent-review (invocation)
  "Review the current staged changes for INVOCATION."
  (let ((changed-files
         (magent-workflow-process
             "List staged files"
             '("git" "diff" "--cached" "--name-only"))))
    (magent-workflow-answer
        "Review staged changes"
        (format
         "Review the staged changes in these files:\n%s"
         changed-files)
      :buffers
      '(agent-shell-mode
        (magit-status-mode :required-p nil)
        ("^\\*Warnings\\*" :regexp t
         :required-p nil :project-only-p nil)
        (my-magent-review-buffer-p :predicate t :required-p nil))
      :skills '("code-review")
      :agent 'build
      :append-argument-p t
      :tools '(read_file grep bash read_tool_output))))

(magent-action-register
 "my-review"
 :description "Run my package-specific review workflow."
 :title "My package review"
 :exposure '(slash)
 :session-policy 'current
 :workflow #'my-magent-review
 :source-layer 'project
 :source-scope "/path/to/project"
 :requires 'diff-mode)

Every registration provides exactly one :workflow function and an explicit :session-policy. The Workflow is an Elisp generator defined with magent-define-workflow. Ordinary Elisp owns branching, loops, local state, validation, and calls into Emacs; managed Steps are used only where the Workflow must suspend for asynchronous work.

:exposure declares the supported entry points: '(slash) (the default), '(interactive), or '(slash interactive). M-x magent-action only offers Actions that include interactive; :session-policy independently controls which session the Action uses.

:modes optionally restricts interactive invocation in the originating buffer:

:modes '(major magit-mode)
:modes '(minor git-commit-mode)
:modes '(or (major org-mode)
            (and (major prog-mode) (minor eglot-managed-mode)))

Major-mode conditions include derived modes. Minor-mode conditions check the mode variable in the originating buffer. and requires every operand; or requires any operand. Empty expressions and arbitrary Lisp are rejected; omitting :modes imposes no mode restriction. Slash calls ignore this field. The effective scoped definition is resolved before filtering: a project override that fails its mode condition never falls back to a global definition. Direct interactive calls recheck the mode before creating an Action/session. Checks such as whether point is on a diff remain Workflow responsibilities.

:requires accepts one Emacs feature symbol or a list of feature symbols. Magent calls require for each feature during invocation preflight. A missing feature leaves the Action discoverable but makes invocation fail before an isolated session is created. This option does not install a package, check for executables, or require a project workspace. The removed :requires-project option has no Action equivalent.

The tuple (NAME, SOURCE-LAYER, canonical SOURCE-SCOPE) is one registry slot. Registering that slot again replaces its previous definition and makes the old registration token stale; unregistering the replacement does not restore the older same-slot definition. Different layers and project scopes remain independent and still participate in normal precedence resolution.

:buffers follows a popwin-style ordered pattern list:

• A buffer object selects that exact live buffer.
• A string selects the buffer with that exact name.
• A symbol selects every buffer whose exact major-mode is that symbol.
• (REGEXP :regexp t ...) selects every buffer whose name matches REGEXP.
• A lambda or closure is called as (PREDICATE BUFFER).
• (FUNCTION-SYMBOL :predicate t ...) names a buffer predicate explicitly.

A bare pattern is required, so '(magent-buffer magit-buffer) means two required major-mode selectors. Expanded entries accept :required-p, :regexp, :predicate, and :project-only-p. A required pattern that matches nothing stops the Action before submission; an optional one is logged and skipped. Selector patterns (mode, regexp, and predicate) match all live buffers in buffer-list order and default to project-only when the session has a project. Exact buffer and exact-name patterns default to no project filter. Set :project-only-p explicitly to override either default. Results preserve configuration order and are deduplicated by buffer identity.

Magent snapshots matched buffers immediately before runtime submission. An active region wins; otherwise the current accessible range is captured, so narrowing is respected. Text properties are removed. Each snapshot is a structured user resource containing the buffer name, mode, file, modified state, point, selected bounds, retained bounds, narrowing state, and content. The immutable snapshot is persisted with the user turn and reused during later ledger replay; subsequent edits to the live buffer do not rewrite history.

magent-action-buffer-context-max-chars limits the combined buffer content to 24000 characters by default. Earlier :buffers entries have priority. A snapshot that exceeds the remaining budget keeps a point-centered window and includes a model-visible truncation marker. This budget counts captured buffer content, not the resource metadata header.

The model-visible user content order is the expanded Action prompt, Action buffer snapshots, then frontend attachments. append-argument-p defaults to nil for an agent Step. Set it to non-nil to append trailing slash text as an Additional instruction block; leave it nil when the Workflow has already consumed magent-action-invocation-argument. Project scope, frontend facts, and attached resource paths still belong to the Action Invocation and are inherited automatically.

Request context is runtime metadata, not extra model input. Recognized fields may affect project instruction discovery, capability resolution, or runtime routing, but the plist is not serialized verbatim for the model. Agent and Answer Steps may set step-local :request-context and model-visible :resource-blocks. Magent owns canonical Action metadata. Put other model-visible instructions and data in the prompt, :buffers, or an attached resource.

The managed Step forms are:

• magent-workflow-agent-turn runs an intermediate model turn and returns its text by default. It accepts :agent, :skills, :buffers, :append-argument-p, :tools, :effort, :thinking, :request-context, :resource-blocks, and :result.
• magent-workflow-answer accepts the same model options but is terminal. It streams the final answer, ends the Invocation, and does not resume forms

after the Step.

:tools is the exact provider tool allowlist for that Step, not merely a preflight requirement. Unknown or unavailable names fail before submission. :effort accepts auto, minimal, low, medium, high, or xhigh. :thinking accepts auto, enabled, or disabled. These values are frozen with that Step’s request; explicit disabled suppresses :effort and fails before dispatch if the selected reasoning-capable provider has no guaranteed disable mapping.

• magent-workflow-process runs only a non-empty argv list of strings. It captures the call-site directory and process environment, and accepts :directory, an :environment override alist, :timeout, :check, :result, :record-command, and :record-output. The default result is complete stdout; :result 'full returns a magent-action-process-result including stderr, exit status, duration, and timeout state. Process Steps are local-only: a remote captured or explicit directory fails before process creation. Use an agent Step with the bash tool when an Action intentionally needs project-host execution.
• magent-workflow-callback adapts an existing asynchronous Elisp API. Its start function receives DONE, calls (DONE STATUS VALUE) exactly once with completed, failed, or cancelled, and may return a zero-argument cancellation function.

magent-action-process-timeout is the default process deadline (300 seconds). magent-action-step-output-max-chars bounds process and formatted callback output persisted in the activity ledger (24000 characters); the value returned to Workflow Elisp remains untruncated.

A Workflow that reaches its end returns either a user-visible string or nil. Failed process, agent, and callback Steps signal typed magent-action-*-error conditions inside the generator, so ordinary condition-case can recover. Cancellation is terminal and does not resume the Workflow. magent-action-progress remains available for notification-only updates; Step start/finish activity is recorded automatically.

Agent and Answer Steps use the runtime FIFO. Process and callback Steps are owned and cancellable by their Invocation but do not consume the global agent execution slot, so different Invocations may overlap those external waits. Project-local Markdown never receives trusted Workflow execution authority.

Every instruction skill visible in the exact runtime session scope is advertised through ACP as $name, which agent-shell renders as /$name. Submitting /$name optional instruction preserves that text as the ordinary user turn and explicitly selects the skill for that turn. It does not create an Action Invocation. Tool-type skills are not projected. /skills lists the same scope-aware instruction descriptors locally without contacting the provider. Skills are never projected into the Action registry.

Project Action definitions are retained under their canonical project scope. magent-action-get, magent-action-list, and magent-action-parse accept an optional scope, and ACP always supplies the runtime session’s scope for both advertisement and dispatch. The skill descriptor catalog follows the same scope rule and retains inactive project snapshots. Concurrent sessions for different projects can therefore expose same-name Action or skill overrides without leaking entries between menus.

Magent scans the current project’s .magent/actions/*.el in filename order (top-level non-hidden source files only). Each file contains ordinary trusted Elisp definitions and calls to magent-action-register. Registrations automatically receive :source-layer 'project and the canonical project scope; files cannot use this API to register into another scope or source layer. For example, save this as .magent/actions/check.el:

;;; -*- lexical-binding: t; -*-
(magent-define-workflow my-project-check (_invocation)
  (magent-workflow-process "Run project checks" '("make" "check")))

(magent-action-register
 "project-check"
 :description "Run this project's checks."
 :exposure '(slash interactive)
 :session-policy 'isolated
 :workflow #'my-project-check)

Opening M-x magent-action discovers approved files without prompting. Choose manage: reload-project to approve new or changed files and load their Actions; open the picker again to select them. Approval covers the complete set of filenames and source contents, stored locally in magent-action-project-trust-file. Added, removed, or changed source requires new approval before execution. Evaluation uses the approved in-memory snapshot. These files have full live Emacs access; approval is not a sandbox or a promise about code loaded indirectly by those files. Keep top-level code limited to definitions and registration: arbitrary Lisp side effects cannot be rolled back.

Background/chat discovery does not prompt or execute unapproved files. Use M-x magent-action-trust-project from a project buffer to approve files for chat use, or to reconsider a declined snapshot. magent-action-reload-project explicitly reruns approved sources; magent-action-forget-project-trust removes the approval and current file registrations. Normal discovery and invocation notice content changes without a file watcher. Deleting all Action files removes their registrations. A load error reports the filename, publishes no partial project registrations, and leaves other projects intact. Previously running invocations retain their captured Workflows.

M-x magent-action-run-doctor collects bounded evidence through trusted read-only probes, recursively redacts it, and sends one request without model tools. With a prefix argument, C-u M-x magent-action-run-doctor lets the user review applicable probe selection. See DOCTOR.org for the probe API and security boundary.