Skip to content
YggdraSIM

Plugin contract

Plugins extend YggdraSIM with optional capabilities that the core must stay runnable without. This page documents the exact contract the plugin runtime expects, the reserved capability names, and the behavior when a capability is absent.

On this page

Discovery

The plugin runtime in yggdrasim_common/plugin_runtime.py scans the plugins/ directory under the active runtime root. It loads:

  • single-file plugins plugins/<name>.py (underscore-prefixed names are skipped)
  • package-style plugins plugins/<name>/ with an __init__.py (skipped if that file is missing)

Directory plugins load canonically as plugins.<name> so package-relative imports work in source and drop-in runtime installs. The legacy yggdrasim_plugin_<name> name remains an alias to the same module object. Single-file plugins retain the legacy synthetic name. Load errors are captured per plugin and surfaced back to the runtime, not raised globally. A broken plugin must not break the rest of the process.

Registration contract

Each plugin module must expose a callable:

def register_plugins(manager):
    manager.register_capability("<capability-name>", <provider>)

The manager argument is the PluginManager instance. Capability names are lowercased and stripped. Empty names are rejected.

Capability manager

The manager exposes:

Method Purpose
register_capability(name, provider) register a capability
get_capability(name) retrieve a capability (loads plugins lazily)
ensure_loaded() force-load plugins (idempotent)
load_errors() surface any per-plugin load errors

Consumers call get_capability("<capability-name>") and branch on whether it returns a provider.

A provider whose extend_target raises is recorded under <capability-name>:extend in load_errors(), and the providers after it still extend the target. An ActionSpec or ActionField built with a non-str text field is refused with a TypeError naming the spec at construction (the usual cause is a trailing comma inside a parenthesised run of string literals, which makes the field a tuple), so a malformed action becomes that plugin's load error while GET /api/actions keeps serving every other action.

Reserved capability names

Reserved names are private extension contracts. Public distributions should document only the generic loader behavior and keep undistributed capability names out of shipped docs.

mcp_extensions

The one capability whose name is published, because the consumer that reads it ships too. It lets a private plugin add tools, resources, and prompts to the MCP server without any operator specifics entering this tree.

A provider exposes register(mcp) and may expose the usual health():

class OperatorMcpExtensions:
    def health(self) -> dict:
        return {"actions_available": True, "dependency_issues": []}

    def register(self, mcp) -> None:
        @mcp.prompt()
        def house_profile_review(file_path: str = "") -> str:
            return f"Review {file_path} against the house profile rules ..."

        @mcp.tool()
        def operator_plmn_lookup(mccmnc: str) -> str:
            ...


def register_plugins(manager) -> None:
    manager.register_capability("mcp_extensions", OperatorMcpExtensions())

Tools/YggdraMCP/server.py::load_plugin_extensions calls it at startup and reports rather than raises at every step: a provider that is absent, declares itself unavailable, raises from health(), lacks register, or raises from register is logged and skipped, and the server still serves its built-in surface.

A plugin tool that drives a card must call card_access_allowed() from the server module and refuse when it returns False. The loader cannot enforce that on a plugin's behalf, and a plugin that ignores it silently widens the gate the built-in card tools sit behind.

Plugin consoles

A plugin can give the GUI a console without shipping browser code. The core owns one generic view and one route family (/api/plugin-consoles); the plugin hands over a manifest that declares what the view may render and an object that answers the calls. The console is listed in the left rail's Plugin consoles group when the GUI starts with plugin loading allowed; the group is not shown while no console is registered. A console is the GUI half of a capability; the same command language still needs its CLI verb.

The provider's extend_target receives a PluginConsoleRegistry and calls add_console(console):

class CounterConsole:
    def manifest(self) -> dict:
        return {
            "id": "counter",
            "title": "Counter",
            "start": {"fields": [{"name": "step", "label": "Step", "type": "number", "min": 1, "default": 1}]},
            "actions": [
                {"id": "add", "label": "Add", "template": "ADD {amount}",
                 "fields": [{"name": "amount", "label": "Amount", "type": "number"}]},
            ],
            "command_line": {"placeholder": "HELP"},
            "streams": [
                {"id": "log", "title": "Log",
                 "columns": [{"key": "at", "label": "Time", "format": "time"},
                             {"key": "text", "label": "Message"}]},
            ],
        }

    def status(self) -> dict: ...
    def start(self, values: dict) -> dict: ...
    def stop(self) -> dict: ...
    def command(self, line: str) -> dict: ...
    def stream(self, stream_id: str, after: int) -> dict: ...
    def help(self) -> dict: ...


class CounterCapability:
    def __init__(self) -> None:
        self._console = CounterConsole()

    def extend_target(self, target) -> None:
        if type(target).__name__ == "PluginConsoleRegistry":
            target.add_console(self._console)

The registry is filled once per process, on the first request after the plugin gate has latched. add_console validates the manifest (yggdrasim_common/gui_server/plugin_console_manifest.py) and checks the methods it depends on; a console that does not fit is listed as refused with the reason, which the GUI log shows, and never reaches the view. The registry lists at most 16 consoles and keeps at most 32 refusals.

Manifest

Key Shape
id [a-z][a-z0-9_-]{0,31}; the URL segment and the nav leaf
title, summary one line each, at most 60 and 240 characters
start optional {label, fields}; the operator starts and stops such a console, and its actions and command line are enabled only while it runs; a text field may carry fill: {label}, a button beside it that asks the console for the field's value
actions up to 48 {id, label, template, fields, group, hint, place}; group sorts the buttons under headings; place is actions (the default: a card on the Actions tab) or compare (a button in the comparison panel's toolbar, which needs compare declared)
command_line optional {placeholder, hint}; its presence enables the free command line
streams up to 4 {id, title, columns}; a column is {key, label, format, width} with format text, time (epoch seconds), hex or mono (text in the mono font with its spacing kept: a captured terminal) and width narrow, medium or fill (the default; a time column is always narrow and takes no width)
compare optional comparison panel {title, hint, sides}: 2 to 4 sides {id, label}, filled by the status answer (see Comparison panel below)
state optional {title}: the state the status reports gets a tab of its own under that title (default State); without it the state is listed under the start form
pills up to 3 {id, label} top bar pills, a label of at most 20 characters; pills() answers them (see Top bar pills below)
runs optional run form: variants of selectable items, their fields and the stored credentials they need (see Run forms below)

A field is {name, label, type, default, required, placeholder, hint} with type text (plus pattern, max_length), number (min, max, step), boolean, choice (options, each {value, label}) or reader (a PC/SC or remote reader name the view offers from the live reader list; empty leaves the pick to the plugin). Any other key, at any level, refuses the whole manifest.

An action's template names each of its fields once, as {name}; the fields are always required and are text, number or choice. The server renders the line and refuses a value that is not one word or that starts with -, so a field never adds words or options to the line. The console receives the rendered line through command(line) exactly as a typed one, and the transcript shows it, so a button teaches the command it stands for.

Methods

Method Needed when Returns
manifest() always the manifest above
status() always {running, busy, last_error, state}, plus compare when the manifest declares one; busy is a phase label shown while it lasts, state a plain object the view lists as key / value rows
start(values), stop() start is declared the status after the change; values holds every start field, checked
fill(field, values) a start field declares fill {value, note}: the field's value, cut to its length, worked out from the other start values (checked, none required yet; the field's own half-typed value is left out)
command(line) actions or a command line are declared {output}
stream(stream_id, after) streams are declared {entries, next}: the entries after cursor after and the cursor to ask from next
pills() pills are declared {<pill id>: {value, state}}: a pill left out or with an empty value is not shown; state is ok, warn, error, busy or idle
help() optional {groups: [{group, commands: [{name, usage, summary, aliases}]}], text}

A ValueError from a call answers 422, a RuntimeError 409 and anything else 500. The polls never fail: status reports a provider error as last_error, a stream as its error. Every answer is copied into bounded plain JSON (plugin_console_output.py) before it is sent, and the view renders it as text only.

The routes are GET /api/plugin-consoles (the consoles and the refusals), GET /api/plugin-consoles/pills (every console's pills that carry a value), GET .../{id}/status, POST .../{id}/start, POST .../{id}/stop, POST .../{id}/fill ({field, values}), POST .../{id}/command ({line} or {action, values}), GET .../{id}/stream?cursor=<stream>:<n> (the status and every stream in one answer) and GET .../{id}/help. They sit behind the GUI's bearer token like every /api/* route.

Layout

The view is two panes, each with a tab per part the manifest declares: controls (Session, the state tab, Actions, or Command line when the console declares no actions, the run form and the credentials) and output (the comparison, one tab per stream, the runs). A pane with one part shows no tab strip, and a pane with none leaves the other the whole width. The panes fill the window and scroll on their own, so no part sits below another pane's content; below 960 px they stack and the page scrolls. The tab picked per console and pane is kept in the viewer's browser storage. An action's answer shows under its own card (its first four lines) as well as in the transcript.

A stream table has fixed column widths from the manifest, so a new row never re-measures the ones before it: a fill column takes what the narrow and medium ones leave, and below each column's minimum the table scrolls sideways. Time, hex and narrow text stay on one line and are cut at the column edge, with the whole value as a tooltip; a click opens that row, and the table's Wrap shows every value in full. A table keeps its newest 1000 rows and follows new rows while it is scrolled to the bottom, also across a tab switch.

Top bar pills

A console that reports something worth seeing from any view (a session's network, an open channel) declares pills and answers pills():

{"network": {"value": "001/01 E-UTRAN normal", "state": "ok"},
 "channel": {"value": "1 open", "state": "ok"}}

The top bar polls GET /api/plugin-consoles/pills every 5 seconds while the page is visible and shows each pill with a value beside the bridge pills: the label, the value (one line, cut at 48 characters) and a dot in the tone of state (ok green, warn and busy in the warn and accent colours, error red). A click opens the console. Nothing is shown for a console that answers no value, so a stopped session takes no room. On a narrow window the values fold away first (below 1760 px, the title keeps the whole text), then a console's further pills (below 1400 px). A console whose pills() raises drops out of that answer; the others stay.

Comparison panel

A console that shows two or more views of the same thing side by side (a card read from the reader beside a platform's record of it) declares compare with its sides and returns the panel with every status() answer:

{"compare": {"note": "...", "sections": [{"title": "Profiles", "rows": [
    {"label": "8988201234567890123", "cells": {"card": "enabled", "platform": "disabled"}, "verdict": "differs"},
]}]}}

The plugin decides each row's verdict: same, differs, missing (present on one side only) or info (a row that is not compared); anything else reads info. plugin_console_output.compare_payload keeps one text cell per declared side (a cell for any other side is dropped, a missing one reads empty), at most 24 sections of 256 rows and 2048 characters per cell, on every path that answers a status (status, start, stop and the stream poll); a console that declares no comparison never passes one on. The view renders one table per section in the output pane's comparison tab, with the item, one column per side and the verdict (differs in the warn colour, one side only in the fail colour), and redraws only when the answer changed. Each section folds on its heading, which also counts its rows and what differs; a redraw keeps the sections as they are, and the folded ones are remembered per console in the browser. An action with place: compare renders as a button in the toolbar above the tables, its fields beside it, and answers in the box under the toolbar (the first lines, prefixed with the action's label); the transcript on the Actions tab keeps the whole answer.

Run forms

A console that starts runs (a test suite, a batch job) declares runs instead of, or beside, a session. The view renders a variant select, the fields every run uses, one card per item (ticking it opens the item's own fields inline) and the field groups the ticked items use, placed before or after the items; the output pane's runs tab follows the current run and lists the earlier ones, and the credentials have a tab of their own. plugin_console_runform.py validates the section:

Key Shape
labels optional titles form, variant, items, credentials, start, cancel, current, history, empty_history; each defaults to generic wording
fields up to 8 fields every run uses, rendered first (an operator signature, a title)
groups up to 16 {id, label, place}; place is before_items (beside the credentials) or after_items
credentials up to 8 {id, label, hint, named, fields, labels}: secrets the plugin stores once (an API key and its base URL, or a client certificate's settings and key passphrase), up to 8 text fields, at least one secret; named keeps several entries (below); labels may rename the store, forget and replace buttons (at most 24 characters each: a sign-in whose secret is used once and never kept reads Sign in / Sign out)
variants 1 to 8 {id, label, summary, available, unavailable_reason, credentials, fields, items}; credentials names the ones the variant's items may need, each shown in the form as a status line with a button to the credentials tab
accepts_while_running optional flag: a start while a run is in progress is accepted, and the console adds it to that run (its answer names the run in progress, which the view keeps following); without it the view refuses a start until the run is done

A run field is a form field plus group (a declared group id), secret (a text field typed into a password box, with no default), visible_when: {field, equals}, which hides the field until an earlier field holds that value (equals has the controlling field's type), and, for a choice, options_from: the name of a list the console's status answer carries under choices, which fills the field's options instead of the manifest, so the operator picks a profile or an eIM by name and the plugin receives the value behind it. Such a field declares no options and no default, cannot control another field, shows a blank first option until the operator picks, and a start is checked against the list current at that moment; plugin_console_output.choices_payload keeps at most 64 {value, label} per declared source (values of at most 64 characters, labels of 60, an empty or repeated value dropped) and drops any source no field declares. An item is {id, label, summary, badge, available, unavailable_reason, fields, credentials, auto_when}: fields names the variant fields it uses and credentials the stored secrets it needs. A field no item names is always in use. A field several items name must carry a group, and a controlling field must be in use whenever the field it controls is. auto_when: {field, equals} selects the item from an always-used field instead of a tick.

The server repeats the view's selection (plugin_console_selection.py, mirrored by pcRunPlan in the view and held to one table by the tests): a field is visible when it is in use and its controller is visible and holds the wanted value. Only visible fields are checked and passed on, so a hidden or unused value never reaches the plugin; a visible required field that is blank refuses the start, and so does a needed credential that is not usable.

A named credential keeps several entries on the plugin's side, each under a name the operator gives it: one word of 1 to 40 letters, digits, ., _ or -, starting with a letter or a digit (ENTRY_NAME in plugin_console_runform.py), unique within the credential. Its panel in the credentials tab lists the entries (Replace, Forget) and Add opens a Name field beside the credential's own fields; the form's status line for it carries "Use for this run", which picks the entry a run uses. The view preselects the only usable entry, and Run stores a typed entry first and uses it. The pick is not a form field and stays out of the selection: the request carries it as credential_entries, and a start is refused while a needed named credential has no pick naming a usable entry. A refusal never repeats a name back, in case a secret was typed into it.

Method Returns
status() also active_run: the id of the run in progress, which the view attaches to, or empty; and choices: {<source>: [{value, label}]} for the fields declared with options_from
run_start(request) the new run's history row; request is {variant, items, auto_items, values, credentials}, plus credential_entries ({credential id: entry name}) when a needed credential is named
runs(limit) history rows, newest first: {id, status, title, summary, time}
run(run_id) {id, status, title, meta, error, results}; a result is {label, status, note, checks: [{ok, text}], details: [{summary, text}]}
run_events(run_id, after) {entries: [{time, level, text}], next, finished}; level is info, ok, warn or error
run_cancel(run_id) {cancel_requested}
credentials() {<id>: {stored, usable, summary, values}}; values may carry the non-secret fields; a named credential answers {summary, entries: [{name, usable, summary, values}]}
credential_store(id, values), credential_forget(id) that credential's entry; for a named credential they take the entry name as one more argument (credential_store(id, values, name), credential_forget(id, name)) and answer the whole credential

The credential trio is needed only when the form declares credentials. Run states are queued, running, passed, failed, error and cancelled, result states pending, running, passed, failed, error and skipped; anything else reads unknown. The answers are cut to these shapes in plugin_console_runs_output.py: a credential answer keeps stored, usable, the summary and the declared non-secret values (a named one at most 32 entries, each well-formed name once in any case, with the same keys), so a stored secret cannot reach the page even when a provider returns it. A KeyError from a run call answers 404.

The routes are POST .../{id}/runs ({variant, items, values}), GET .../{id}/runs?limit=, GET .../{id}/runs/{run_id}, GET .../{id}/runs/{run_id}/events?after=, POST .../{id}/runs/{run_id}/cancel, GET .../{id}/credentials and POST / DELETE .../{id}/credentials/{credential_id} ({values}; a named credential's entry is {name, values} and ?name=, and a plain credential refuses a name). A run start may carry credential_entries.

APDU trace renderer

SCP11.transport.set_apdu_trace_renderer(renderer) hands every raw-mode exchange of the SCP11 transport (a command run with --debug, or the global debug flag) to renderer(label, command, response, sw1, sw2) in place of the built-in [label] > HEX and [label] < SW: ... Data: ... lines, and returns the renderer it replaced. There is one slot for the whole process, so a provider installs its renderer from extend_target and every SCP11 shell's channel prints through it; concise-mode lines do not change. A renderer that raises leaves that exchange to the built-in lines, and while a renderer is installed send_chunked drops its per-block line, because the label the renderer receives already names the block. With no renderer installed the transport prints as it always has.

SCP11.transport.set_apdu_trace_note_renderer(renderer) is the second slot, for the lines a flow prints between those exchanges while the global debug flag is on: the connect phase's heading (Phase: Connect) and the lines on the logical channel ES10b settled on (ES10b logical channel active: CH1.). A flow prints such a line with print_apdu_trace_note(text, heading=...); renderer(text) receives the text in place of the built-in [*] text line, and the setter returns the renderer it replaced. A heading's blank line belongs to the built-in form only. With the debug flag off nothing reaches the renderer, and a renderer that raises leaves the line to the built-in form.

Absent-plugin behavior

The contract says:

  • The core must remain runnable without any plugin installed.
  • A consumer that depends on a capability must either hide the verb that depends on it, or emit a clean runtime error that explicitly states the capability is optional.
  • A broken plugin's error is captured and reported; it does not prevent other plugins from loading or the rest of the shell from running.

Runtime root note

Plugins live under the active runtime root, not the source tree. In source runs that is the repository plugins/ tree. In frozen builds that is the writable runtime root's plugins/ directory. See Runtime Root.

Publication policy

plugins/README.md documents the publication-ignore stance: the loader contract ships in the published core, but plugin implementation files are intentionally ignored by default. Keep private plugins under the runtime root only.