Module widget_packages 

Widget packages: user widgets as folders with a widget.json manifest, which run only once the user approves them (docs/specs/SPEC_USER_WIDGETS_AND_WIDGET_API_2026_10_09.md §5, §8).

srv scans ~/.agentmux/widgets/ (shared by every channel), validates each package’s manifest, hashes every file, and keeps this instance’s approval record. A package’s files are served (/agentmux/widget-files/…) only while they still hash to what the user approved, checked per file on every read, so an edit after approval can’t run until it is approved again — whether or not the folder watcher saw it.

Structs

Approval

Budget 🔒

What a package may still take while it is copied or unpacked: the limits apply to the bytes actually written, so neither a large folder nor a zip whose header understates its sizes can fill the disk before hash_files.

Found

A package found on disk, before approval is applied.

Inner 🔒

Manifest

ManifestCommand

A command palette entry (spec §6.8).

ManifestContributes

ManifestPane

ManifestStatusItem

A status bar item (spec §6.8).

WidgetCommandInfo

A palette command, as the UI registers it (spec §6.8).

WidgetPackageInfo

WidgetPackages

srv’s view of the widgets folder and this instance’s approvals.

WidgetPaneInfo

WidgetStatusItemInfo

A status bar item, before any pane of the widget updates it.

Enums

FileError

StatusAlignment

WidgetKind

WidgetState

Constants

APPROVALS_FILE 🔒

MANIFEST_FILE

MANIFEST_VERSION

MAX_COMMANDS

Palette commands and status bar items a package may add (spec §6.8).

MAX_PACKAGE_BYTES

MAX_PACKAGE_FILES

MAX_STATUS_ITEMS

PERMISSIONS

Every permission a manifest may ask for (spec §6.4). net:<origin> is checked separately.

PUBLISHERS_FILE 🔒

Publisher → the key its first approved signed package was signed with.

WIDGET_CSP

The policy every widget file is served with (spec §6.1).

Statics

SERVICE 🔒

Functions

content_type

The content type a widget file is served with.

copy_tree 🔒

describe

Combine what’s on disk with this instance’s approvals and pins.

files_key

The files URL’s unguessable part: HMAC(instance secret, id, hash), so a web page outside AgentMux can’t name a package’s files (they aren’t secret, but nothing else needs them).

hash_files

Every file in dir (relative path → SHA-256 hex), within the limits, with no symlinks. widget.sig at the root is left out: it signs the hash of the rest (SPEC_WIDGET_SHARING_2026_10_10.md §2.1).

implied_from_v1

A v1 widgets.json entry with a module as an implied trusted package (spec §5.5): its one module file is the package.

install

Copy the package at source (a folder, a widget.json in one, or a .zip) into the widgets folder; returns its id. Validates first; refuses to replace an existing package unless replace.

is_slug 🔒

package_hash

The package’s content hash: SHA-256 over each file’s path and hash, in path order. Any change to any file changes it.

pane_view 🔒

The view a pane opens as: ext:<id>/<name>, or a v1 widget’s own name.

publish

Tell every UI the package list (Settings → Widgets and the loader follow it).

put_in_place 🔒

Moves the staged package to dest, or copies it when they’re on different drives.

read_approvals

refresh

Scan again, merge the widget bar again, and tell every UI.

refresh_off_thread

refresh on a blocking thread: a rescan reads and hashes every file of every package, which mustn’t stall an async worker.

scan

Every folder in widgets_dir (a missing folder is none).

service

start

Start the service: scan, merge, and watch the widgets folder.

unzip 🔒

valid_icon 🔒

A Font Awesome name: lowercase letters, digits and -.

valid_id

valid_permission

A permission is a known name, or net:<origin>: http(s)://host[:port], where host may start with *. (subdomains), never a bare *.

valid_rel_path 🔒

A path inside a package: relative, /-separated, no ...

valid_semver 🔒

validate

Check a manifest; the first problem, in words the user can act on.

validate_contributions 🔒

contributes.commands and contributes.statusItems (spec §6.8).

widget_entries

The widget-bar entries an approved, enabled package adds, keyed ext@<id>/<name> (spec §5.4). v1 widgets already have theirs.

widgets_dir

~/.agentmux/widgets, shared by every channel (spec §3, decision 5).

write_approvals

yes 🔒

Type Aliases

Approvals