Minga.Extension.Agent (Minga v0.1.0)

Agent surface for Minga extensions.

This module provides the DSL macros and compile-time wiring for agent-specific extension components: hooks, skills, MCP servers, slash commands, and semantic UI contributions.

use Minga.Extension.Agent is the recommended way to define an extension that contributes agent-side features. It injects the Minga.Extension behaviour, registers compile-time accumulate attributes for each agent component, provides a default child_spec/1, and imports the agent DSL macros.

Agent extensions can also declare config options with option/3, just like editor extensions.

Types

Hook specs are {event, opts} tuples where event is an atom like :pre_tool_use or :session_start and opts is a keyword list with keys like :tool, :command, etc.

Skill specs are path strings pointing to a skill directory on disk.

MCP server specs are {name, opts} tuples where name is an atom or string identifier and opts is a keyword list with keys like :command and :args.

Slash command specs are {name, description, opts} tuples where name is an atom or string, description is a human-readable string, and opts is a keyword list with keys like :command.

Agent UI specs are maps or keyword lists that already contain semantic render-model values. The semantic UI registry validates that payloads are existing Minga.RenderModel.UI.* values before render builders read them.

Usage

defmodule MingaLint do
  use Minga.Extension.Agent

  option :auto_fix, :boolean,
    default: false,
    description: "Automatically apply lint fixes"

  hook :pre_tool_use, tool: "write_*", command: "hooks/lint.sh"
  hook :session_start, command: "hooks/hello.sh"

  skill "skills/greet"

  mcp_server :my_mcp, command: "servers/my-mcp", args: ["--port", "3000"]

  slash_command :my_cmd, "Runs my custom command", command: "commands/my-cmd.sh"

  agent_ui id: "status", surface: :panel, payload: %Minga.RenderModel.UI.ExtensionPanel.Panel{...}

  @impl true
  def name, do: :minga_lint

  @impl true
  def description, do: "Linting hooks for agent sessions"

  @impl true
  def version, do: "0.1.0"

  @impl true
  def init(_config), do: {:ok, %{}}
end

For extensions that contribute editor-side components (commands, keybindings, modeline segments, capabilities), see Minga.Extension.Editor.

Summary

Functions

__using__(opts)

Injects the Minga.Extension behaviour, agent DSL macros, and a default child_spec/1.

agent_ui(attrs)

Declares a semantic agent UI contribution.

hook(event, opts)

Declares a lifecycle hook this extension provides.

mcp_server(name, opts)

Declares an MCP server this extension provides.

skill(path)

Declares a skill directory this extension provides.

slash_command(name, description, opts)

Declares a slash command this extension provides.

Functions

using(opts)

(macro)

Injects the Minga.Extension behaviour, agent DSL macros, and a default child_spec/1.

The injected macros are: option/3, hook/2, skill/1, mcp_server/2, slash_command/3, and agent_ui/1.

At compile time, each macro accumulates declarations into module attributes. The __before_compile__ hook then generates __option_schema__/0, __hook_schema__/0, __skill_schema__/0, __mcp_server_schema__/0, __slash_command_schema__/0, and __agent_ui_schema__/0 functions that the framework reads at load time.

agent_ui(attrs)

(macro)

Declares a semantic agent UI contribution.

The payload must be an existing render-model value accepted by MingaEditor.Agent.SemanticUI.Entry, such as an agent chat message body, extension-panel content, or an extension-panel panel.

Examples

agent_ui id: "status", surface: :panel, payload: %Minga.RenderModel.UI.ExtensionPanel.Panel{...}
agent_ui id: "note", surface: :transcript_enrichment, payload: {:system, "Ready", :info}

hook(event, opts)

(macro)

Declares a lifecycle hook this extension provides.

Hooks fire at specific agent lifecycle events and can run shell commands or invoke functions.

Accumulated at compile time and exposed via __hook_schema__/0.

Options

:command (required) -- path to the script or executable to run
:tool -- glob pattern to match tool names (only for tool-related events)

Examples

hook :pre_tool_use, tool: "write_*", command: "hooks/lint.sh"
hook :session_start, command: "hooks/hello.sh"

mcp_server(name, opts)

(macro)

Declares an MCP server this extension provides.

MCP (Model Context Protocol) servers expose tools and resources to the agent through a standardized protocol.

Accumulated at compile time and exposed via __mcp_server_schema__/0.

Options

:command (required) -- path to the server executable
:args -- list of command-line arguments (default: [])

Examples

mcp_server :my_mcp, command: "servers/my-mcp", args: ["--port", "3000"]
mcp_server :db_tools, command: "servers/db-tools"

skill(path)

(macro)

Declares a skill directory this extension provides.

Skills are directories containing agent instructions, prompts, and tool definitions that extend the agent's capabilities.

Accumulated at compile time and exposed via __skill_schema__/0.

Examples

skill "skills/greet"
skill "skills/refactor"

slash_command(name, description, opts)

(macro)

Declares a slash command this extension provides.

Slash commands are user-invokable agent commands prefixed with / in chat interfaces.

Accumulated at compile time and exposed via __slash_command_schema__/0.

Options

:command (required) -- path to the script or executable to run

Examples

slash_command :my_cmd, "Runs my custom command", command: "commands/my-cmd.sh"
slash_command :deploy, "Deploy the current branch", command: "commands/deploy.sh"