Plugins

~/.mibyan/plugins/my-plugin/
├── plugin.yaml      # manifest
├── __init__.py      # register() — wires schemas to handlers
├── schemas.py       # tool schemas (what the LLM sees)
└── tools.py         # tool handlers (what runs when called)

name: hello-world
version: "1.0"
description: A minimal example plugin

"""Minimal Mibyan plugin — registers a tool and a hook."""

import json

def register(ctx):
    # --- Tool: hello_world ---
    schema = {
        "name": "hello_world",
        "description": "Returns a friendly greeting for the given name.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {
                    "type": "string",
                    "description": "Name to greet",
                }
            },
            "required": ["name"],
        },
    }

    def handle_hello(params, **kwargs):
        del kwargs
        name = params.get("name", "World")
        return json.dumps({"success": True, "greeting": f"Hello, {name}!"})

    ctx.register_tool(
        name="hello_world",
        toolset="hello_world",
        schema=schema,
        handler=handle_hello,
    )

    # --- Hook: log every tool call ---
    def on_tool_call(tool_name, params, result):
        print(f"[hello-world] tool called: {tool_name}")

    ctx.register_hook("post_tool_call", on_tool_call)

plugins:
  enabled:
    - my-tool-plugin
    - disk-cleanup
  disabled:       # optional deny-list — always wins if a name appears in both
    - noisy-plugin
  # Optional: deadline (seconds) for each Git clone, fetch or checkout
  # during plugin installation, including automatic memory-provider migration.
  # Default 300; values above 3600 are clamped. A subdirectory install
  # (owner/repo/path/to/plugin) downloads only that folder's files.
  clone_timeout_seconds: 300
  # Optional: wall-clock cap (seconds) for timeout-bounded in-process Python
  # plugin hook callbacks (hot-path observers + pre_tool_call). Default 30;
  # set 0 to disable; values above 600 are clamped. Timed-out pre_tool_call
  # callbacks fail closed (block the tool). Caller-thread hooks such as
  # subagent_stop are never moved onto a timeout worker.
  # Shell hooks keep their own per-entry timeout under the top-level hooks: key.
  hook_callback_timeout: 30
  # Optional: deadline (seconds) for one plugin's import + register() at load.
  # A plugin that overruns it is skipped with the reason "load timed out after
  # Ns" (reported like any other load failure: the startup warning and the
  # in-session `/plugins` listing) and the remaining plugins keep loading; the
  # stuck thread is abandoned. Default 10; set 0 to disable; values above 600
  # are clamped.
  load_timeout_seconds: 10

mibyan plugins                    # interactive toggle (space to check/uncheck)
mibyan plugins enable <name>      # add to allow-list
mibyan plugins disable <name>     # remove from allow-list + add to disabled

mibyan plugins install owner/repo --ref 0123456789abcdef0123456789abcdef01234567

def present(request):
    # Deliver request.command and request.description to your UI, wait for
    # its authenticated human response, then return a request-bound decision.
    choice = send_to_my_ui_and_wait(request)  # once/session/always/deny
    return request.respond(choice)

def register(ctx):
    ctx.register_approval_transport("my-ui", present)

plugins:
  enabled: [my-approval-plugin]

security:
  approval:
    transport: my-ui
    transport_fallback: deny     # default

services.mibyan-agent = {
  # Directory plugin (source tree with plugin.yaml)
  extraPlugins = [ (pkgs.fetchFromGitHub { ... }) ];
  # Entry-point plugin (pip package)
  extraPythonPackages = [ (config.services.mibyan-agent.package.python.pkgs.buildPythonPackage { ... }) ];
  # Enable in config
  settings.plugins.enabled = [ "my-plugin" ];
};

mibyan plugins                               # unified interactive UI
mibyan plugins list                          # table: enabled / disabled / not enabled (bundled backends,
                                             # platforms and the live memory.provider count as enabled)
mibyan plugins search <term>                 # search the Mibyan plugin catalog
mibyan plugins install <name>                # install a catalog entry (repo @ reviewed pinned SHA)
mibyan plugins install user/repo             # install from Git, then prompt Enable? [y/N]
mibyan plugins install user/repo --enable    # request enable; dependency consent still applies
mibyan plugins install user/repo --no-enable # install but leave disabled (no prompt)
mibyan plugins update my-plugin              # pull latest (local edits are autostashed and re-applied)
mibyan plugins remove my-plugin              # uninstall; also drops it from plugins.enabled/disabled/entries
                                             # and resets memory.provider when it was the live provider
mibyan plugins enable my-plugin              # add to allow-list
mibyan plugins disable my-plugin             # remove from allow-list + add to disabled (bundled platforms:
                                             # either spelling works, e.g. photon-platform or platforms/photon)
mibyan plugins capabilities [my-plugin]      # declared vs granted capabilities
mibyan plugins check-updates                 # read-only: is any installed plugin outdated?
mibyan plugins adopt my-plugin               # track a self-cloned plugin dir (read its git origin)
mibyan plugins trust-update-url my-plugin    # confirm a changed update_url after review

mibyan://plugin/install?catalog=NAME               # catalog entry, installs the reviewed pin
mibyan://plugin/install?repo=owner/repo            # any git repo
mibyan://plugin/install?repo=owner/repo&enable=1   # enable the agent plugin after install
mibyan://plugin/install?repo=owner/repo&force=1    # replace an existing install

<a href="mibyan://plugin/install?repo=owner/repo&enable=1">Install in Mibyan</a>

name: my-plugin
capabilities:
  - tools.override        # replace built-in tools
  - llm.model_override    # pick the model for host-owned LLM calls

mibyan plugins capabilities             # all plugins with declared/granted capabilities
mibyan plugins capabilities my-plugin   # one plugin, declared vs granted

result = await ctx.platform_actions.add_reaction(
    platform="telegram", chat_id="-100123", message_id="456", emoji="👍",
)
result = await ctx.platform_actions.set_thread_title(
    platform="discord", chat_id="123", thread_id="456", title="New title",
)
if not result["ok"]:
    print(result["error"], result.get("detail"))

mibyan plugins search telegram    # search the catalog
mibyan plugins browse             # browse every entry
mibyan plugins info <name>        # full details for one entry

mibyan plugins install <catalog-name>

name: voice-assistant-pack
description: STT + streaming TTS + approval relay
author: hyper
version: 1.0.0
plugins:
  - name: mibyan-telegram-business       # bare plugin-catalog name…
    ref: e905f3bc5eeaa5a9dab9bc5155601b3ebec75757
  - repo: owner/approval-relay           # …or explicit owner/repo (or git URL)
    ref: 8f3c2d1a9b4e5f6071829304a5b6c7d8e9f00112
    subdir: plugins/relay                # optional monorepo path
config:                                  # optional, non-secret seeds only
  mibyan-media-studio:
    default_model: flux-3
skills: []                               # declared list only (not auto-installed yet)

mibyan plugins pack show ./mibyan-pack.yaml     # dry-run review
mibyan plugins pack install ./mibyan-pack.yaml  # review → confirm → install
mibyan plugins pack export > mibyan-pack.yaml   # snapshot the current install
mibyan plugins pack export --enabled-only       # only plugins.enabled

plugins:
  scan_on_install: false

Plugins
  ↑↓ navigate  SPACE toggle  ENTER configure/confirm  ESC done

  General Plugins
 → [✓] my-tool-plugin — Custom search tool
   [ ] webhook-notifier — Event hooks
   [ ] disk-cleanup — Auto-cleanup of ephemeral files [bundled]

  Provider Plugins
     Memory Provider          ▸ honcho
     Context Engine           ▸ compressor

memory:
  provider: "honcho"      # empty string = built-in only

context:
  engine: "compressor"    # default built-in compressor

# Active CLI conversation
ctx.inject_message("New data arrived from the webhook", role="user")

# Existing gateway conversation
ctx.inject_message(
    "New data arrived from the webhook",
    role="user",
    session_key="agent:main:telegram:dm:123456789",
)

plugins:
  entries:
    my-plugin:
      allow_gateway_injection: true

result = ctx.call_mcp(
    "knowledge_rag",            # server name from mcp.servers
    "query_knowledge",          # tool on that server
    {"query": "deploy runbook"},
    timeout=30,                 # seconds; clamped to 1–600
)
if result["ok"]:
    print(result["result"])
else:
    print("MCP error:", result["error"])

plugins:
  entries:
    my-plugin:
      mcp_allowlist: ["knowledge_rag", "github"]