branchkit 0.1.0__py3-none-any.whl

branchkit/__init__.py

@@ -0,0 +1,87 @@
+"""BranchKit plugin SDK for Python.
+
+    import asyncio
+    import branchkit
+
+    plugin = branchkit.Plugin()
+
+    @plugin.handle("my.method")
+    async def my_method(params):
+        return {"ok": True}
+
+    asyncio.run(plugin.run())
+
+Handlers may be `async def` (run on the loop) or plain `def`
+(auto-offloaded to a thread, so a blocking body cannot freeze the
+plugin). Stdlib-only by design: importing the SDK forces no third-party
+dependency on any plugin."""
+
+from . import proxy as _proxy
+
+# Route stdlib HTTP through BRANCHKIT_PROXY when sandboxed (per-host
+# tier) — same import-time side effect as the TS SDK's entry module.
+_proxy.install_proxy_from_env()
+
+from .plugin import (
+    PluginCore,
+    RecordingDisabledError,
+    RpcCallError,
+    api_version,
+    error_kind_of,
+    models_dir,
+    plugin_data_dir,
+    plugin_dir,
+)
+from .collection import CollectionMixin, list_opts, scope_collection, scope_group
+from .collection_log import CollectionLogMixin, log_list_opts
+from .debug import DebugMixin
+from .effects import EffectsMixin
+from .hud import HudMixin
+from .log import log
+from .methods_gen import MethodsMixin
+from .mirror import CollectionMirror, MirrorMixin
+from .settings import SettingsMirror, SettingsMixin
+from .commands import (
+    CommandBuilder,
+    capture,
+    command,
+    load_commands,
+    one_of,
+    push_command_group,
+    push_command_specs,
+    push_commands,
+    text,
+    word,
+)
+from .listen import Listener, inherited_listener_count, listen_local
+from .settings_route import method_post, method_url
+from .ui import (
+    Expr,
+    args,
+    confirm_button,
+    expr,
+    input_value,
+    post_button,
+    signal_button,
+    signal_name,
+)
+from .upstream import UpstreamClient, UpstreamResponse
+from .closed_vocab_gen import *  # noqa: F401,F403 — error kinds, directives, effects
+from .contracts_gen import *  # noqa: F401,F403 — method/hook/event/tag constants
+from .log_events_gen import *  # noqa: F401,F403 — observability log-event names
+
+
+class Plugin(
+    CollectionMixin,
+    CollectionLogMixin,
+    EffectsMixin,
+    DebugMixin,
+    HudMixin,
+    MirrorMixin,
+    SettingsMixin,
+    MethodsMixin,
+    PluginCore,
+):
+    """The plugin: JSON-RPC transport plus the generated method wrappers
+    and the state/log/effects/debug/HUD/mirror/settings façades, one
+    class. See PluginCore for the transport contract."""

branchkit/closed_vocab_gen.py

@@ -0,0 +1,95 @@
+# AUTO-GENERATED by emit-sdk — do not edit.
+# Run: just contracts
+
+from typing import NotRequired, TypedDict
+
+# INPUT_DIRECTIVE_* are the closed-vocabulary keys plugins may write
+# into `_platform.input.directives`. Source of truth:
+# `actuator/src/state.rs::InputDirectives::KNOWN_KEYS`.
+INPUT_DIRECTIVE_LIFT_KEYS_ON_DISPATCH = "lift_keys_on_dispatch"
+
+# EFFECT_* are the registered effect names plugins may declare in
+# `provides.effects`. Source of truth:
+# `actuator/src/effects.rs::EffectDef` inventory entries.
+EFFECT_DISABLE_SCREEN_DIM = "disable_screen_dim"
+EFFECT_MUTE_AUDIO_TO_OTHER_APPS = "mute_audio_to_other_apps"
+EFFECT_PAUSE_MICROPHONE_INDICATOR = "pause_microphone_indicator"
+EFFECT_PREVENT_FOCUS_STEAL = "prevent_focus_steal"
+EFFECT_SIGNAL_RECORDING_ACTIVE = "signal_recording_active"
+EFFECT_SUPPRESS_HUDS = "suppress_huds"
+EFFECT_SUPPRESS_KEYBINDS = "suppress_keybinds"
+EFFECT_SUPPRESS_NOTIFICATIONS = "suppress_notifications"
+
+# The full closed-vocabulary sets.
+KNOWN_INPUT_DIRECTIVES = (
+    "lift_keys_on_dispatch",
+)
+
+KNOWN_EFFECTS = (
+    "disable_screen_dim",
+    "mute_audio_to_other_apps",
+    "pause_microphone_indicator",
+    "prevent_focus_steal",
+    "signal_recording_active",
+    "suppress_huds",
+    "suppress_keybinds",
+    "suppress_notifications",
+)
+
+# ERROR_KIND_* are the closed-vocabulary `kind` values the actuator puts
+# in a JSON-RPC error's `data.kind`. Branch on RpcCallError.kind rather
+# than matching the message prose. Source of truth:
+# `actuator/src/fault.rs::ErrorKind`.
+#
+# NOTE: ErrorKind is `str`, deliberately NOT a Literal union of the
+# values below. An actuator newer than this SDK may send a kind that is
+# not listed here, and that must fall through a match rather than fail
+# to parse.
+ErrorKind = str
+ERROR_KIND_NOT_PERMITTED = "not_permitted"
+ERROR_KIND_RECORDING_DISABLED = "recording_disabled"
+ERROR_KIND_NOT_FOUND = "not_found"
+ERROR_KIND_VALIDATION = "validation"
+ERROR_KIND_FORBIDDEN = "forbidden"
+ERROR_KIND_STORAGE = "storage"
+ERROR_KIND_METHOD_NOT_FOUND = "method_not_found"
+ERROR_KIND_INVALID_PARAMS = "invalid_params"
+ERROR_KIND_INTERNAL = "internal"
+
+# ERROR_CODE_FOR maps a kind to the JSON-RPC error code the actuator
+# sends with it. Derived from the kind actuator-side.
+ERROR_CODE_FOR: dict[str, int] = {
+    "not_permitted": -32002,
+    "recording_disabled": -32006,
+    "not_found": -32001,
+    "validation": -32004,
+    "forbidden": -32003,
+    "storage": -32005,
+    "method_not_found": -32601,
+    "invalid_params": -32602,
+    "internal": -32603,
+}
+
+# KNOWN_ERROR_KINDS lists the full closed-vocabulary set.
+KNOWN_ERROR_KINDS = (
+    "not_permitted",
+    "recording_disabled",
+    "not_found",
+    "validation",
+    "forbidden",
+    "storage",
+    "method_not_found",
+    "invalid_params",
+    "internal",
+)
+
+# FaultData is the structured payload of a JSON-RPC error's `data`
+# member. Only `kind` is guaranteed; the rest are populated when they
+# apply. Source of truth: `actuator/src/fault.rs::FaultData`.
+FaultData = TypedDict("FaultData", {
+    "kind": str,
+    "collection": NotRequired[str],
+    "detail": NotRequired[str],
+    "id": NotRequired[str],
+    "op": NotRequired[str],
+})

branchkit/collection.py

@@ -0,0 +1,188 @@
+"""State uniform helpers — the collection façade over the generated
+`collection.*` wrappers. Python twin of plugin-sdk-go/collection.go and
+plugin-sdk-ts/src/collection.ts."""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from .contracts_gen import EVENT_COLLECTION_UPDATED
+
+
+def scope_collection() -> dict:
+    """Every other record THIS PLUGIN owns in the collection is the
+    complement: after the call, the records you own here are exactly the
+    ones you passed. Other plugins' records, and any the user added through
+    Settings, are untouched and invisible to the diff."""
+    return {"kind": "collection"}
+
+
+def scope_group(group: str) -> dict:
+    """Narrows further, to this plugin's records carrying the named group
+    label — and stamps that label on every entry written. The label must be
+    non-empty; an empty one is indistinguishable from "ungrouped" and the
+    platform refuses it."""
+    return {"kind": "group", "value": group}
+
+
+def list_opts(
+    *,
+    since_ms: int | None = None,
+    until_ms: int | None = None,
+    limit: int | None = None,
+    cursor: str | None = None,
+    writer: str | None = None,
+) -> dict:
+    """Build a ListOpts with typed scalar values. `writer` filters to
+    records owned by that writer — pair with `plugin.id` to ask for your
+    own records, the read half of a scoped write."""
+    out: dict[str, Any] = {}
+    if since_ms is not None:
+        out["since_ms"] = since_ms
+    if until_ms is not None:
+        out["until_ms"] = until_ms
+    if limit is not None:
+        out["limit"] = limit
+    if cursor is not None:
+        out["cursor"] = cursor
+    if writer is not None:
+        out["writer"] = writer
+    return out
+
+
+class CollectionMixin:
+    """The uniform state verbs. Composed into `Plugin`."""
+
+    async def get(self, name: str, id: str) -> dict | None:
+        """The record with that id, or None. On a keyed (compacted-changelog)
+        log this is the RAW entry — use `get_compacted` for the folded
+        current state."""
+        res = await self.collection_fetch(id, name)
+        rec = (res or {}).get("record")
+        return rec if isinstance(rec, dict) else None
+
+    async def get_compacted(self, name: str, key: str) -> dict | None:
+        """A keyed log's folded CURRENT state for one key — the point-read
+        half of the compacted-changelog projection (pairs with
+        `list_compacted`)."""
+        res = await self.collection_fetch_compacted(key, name)
+        rec = (res or {}).get("record")
+        return rec if isinstance(rec, dict) else None
+
+    async def list(self, name: str, opts: dict | None = None) -> list[dict]:
+        res = await self.collection_list(name, opts)
+        return (res or {}).get("records") or []
+
+    async def list_compacted(self, name: str, opts: dict | None = None) -> list[dict]:
+        """The compacted-changelog projection of a keyed log — one folded
+        record per key instead of the raw append history."""
+        merged = dict(opts or {})
+        merged["compacted"] = True
+        res = await self.collection_list(name, merged)
+        return (res or {}).get("records") or []
+
+    async def list_page(self, name: str, opts: dict | None = None) -> tuple[list[dict], int]:
+        """Like `list` but also returns the unfiltered total."""
+        res = await self.collection_list(name, opts)
+        res = res or {}
+        return res.get("records") or [], res.get("total") or 0
+
+    async def count(self, name: str) -> int:
+        res = await self.collection_count(name)
+        return (res or {}).get("count") or 0
+
+    async def put(self, name: str, id: str, payload: Any) -> None:
+        """Single-record upsert. An unregistered name auto-registers as a
+        record-keyed dynamic collection — memory-only and EPHEMERAL; declare
+        the collection in the manifest for durable storage."""
+        await self.collection_put(name, [{"id": id, "payload": payload}])
+
+    async def put_many(self, name: str, entries: list[dict]) -> int:
+        """Bulk upsert. Validation runs across all entries before any
+        commit, so a partial batch with one invalid entry leaves the
+        backend untouched."""
+        if not entries:
+            return 0
+        res = await self.collection_put(name, entries)
+        return (res or {}).get("count") or 0
+
+    async def replace(
+        self,
+        name: str,
+        entries: list[dict],
+        scope: dict,
+        *,
+        roles: dict | None = None,
+        label: str | None = None,
+    ) -> dict:
+        """Make the records in scope exactly `entries`: upsert what changed,
+        delete what is absent, skip what is byte-identical. Returns
+        ``{"put": n, "deleted": n, "skipped": n}``.
+
+        Scope is required and never inferred — pass `scope_collection()` or
+        `scope_group(...)`. See notes/DESIGN_COLLECTION_REPLACE.md."""
+        # Refused locally rather than sent: guessing between "everything I
+        # own here" and "the subset under this key space" is how a refresh
+        # silently becomes a wipe.
+        if not isinstance(scope, dict) or scope.get("kind") not in ("collection", "group"):
+            raise ValueError(
+                "replace: scope is required — use scope_collection() or scope_group(name)"
+            )
+        # No early return on empty `entries`: replacing with the empty set
+        # is how a caller CLEARS its scope.
+        res = await self.collection_replace(name, scope, entries, label, roles)
+        res = res or {}
+        return {
+            "put": res.get("put") or 0,
+            "deleted": res.get("deleted") or 0,
+            "skipped": res.get("skipped") or 0,
+        }
+
+    async def put_many_with_roles(self, name: str, entries: list[dict], roles: dict) -> int:
+        """Bulk upsert with per-payload-field display roles (field → role).
+        Roles persist on the collection — pass them on the first put to a
+        new name, then omit."""
+        return await self.put_many_with_display(name, entries, roles, "")
+
+    async def put_many_with_display(
+        self, name: str, entries: list[dict], roles: dict | None, label: str
+    ) -> int:
+        """Bulk upsert that also sets the collection's human-readable label.
+        Pass "" to leave the label unchanged; like roles, it persists."""
+        if not entries:
+            return 0
+        res = await self.collection_put(name, entries, None, label or None, roles)
+        return (res or {}).get("count") or 0
+
+    async def patch(self, name: str, id: str, fields: Any) -> None:
+        """Errors NOT_FOUND if no record with that id exists, or
+        OPERATION_NOT_PERMITTED on collections the state forbids patching."""
+        await self.collection_patch(fields, id, name)
+
+    async def delete(self, name: str, id: str) -> bool:
+        """Single-record delete. Returns whether the record existed."""
+        res = await self.collection_delete_records(name, [id])
+        return ((res or {}).get("deleted") or 0) > 0
+
+    async def delete_many(self, name: str, ids: list[str]) -> tuple[int, int]:
+        """Bulk delete. Returns (deleted, already_absent) so callers can
+        detect drift between their view and the platform's."""
+        if not ids:
+            return 0, 0
+        res = await self.collection_delete_records(name, ids)
+        res = res or {}
+        return res.get("deleted") or 0, res.get("already_absent") or 0
+
+    def subscribe(self, name: str, fn: Callable) -> None:
+        """Run `fn(evt)` whenever `_platform.collection.updated` fires for
+        this collection. The ordered pump awaits an async `fn`, so two rapid
+        updates cannot race. Subscriptions live for the process lifetime."""
+
+        async def _on_updated(params):
+            evt = params if isinstance(params, dict) else {}
+            if evt.get("collection") == name:
+                # Await, don't discard: this is what keeps wire order. Dual
+                # dispatch, same as any handler — a plain-`def` fn offloads.
+                await self._invoke(fn, evt)
+
+        self.on(EVENT_COLLECTION_UPDATED, _on_updated)

branchkit/collection_log.py

@@ -0,0 +1,97 @@
+"""Helpers for log-kind collections — append-only record stores declared
+in the plugin manifest as `kind: "log"`. Sugar over the unified verbs
+(the wire surface is collection.list / collection.fetch /
+collection.delete_records; log-shaped reads are the same list with
+time-window opts). Python twin of collection_log.{go,ts}."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def log_list_opts(
+    *,
+    since_ms: int | None = None,
+    until_ms: int | None = None,
+    limit: int | None = None,
+    cursor: str | None = None,
+) -> dict:
+    """Build a LogListOpts with typed scalar values — field-identical to
+    the unified list opts by design."""
+    out: dict[str, Any] = {}
+    if since_ms is not None:
+        out["since_ms"] = since_ms
+    if until_ms is not None:
+        out["until_ms"] = until_ms
+    if limit is not None:
+        out["limit"] = limit
+    if cursor is not None:
+        out["cursor"] = cursor
+    return out
+
+
+def _record_to_log_entry(r: dict) -> dict:
+    """Project the unified record envelope onto the log view. Lossless: log
+    records carry their append time in timestamp_ms and owner in writer."""
+    return {
+        "id": r.get("id"),
+        "timestamp_ms": r.get("timestamp_ms"),
+        "payload": r.get("payload"),
+        "writer": r.get("writer"),
+    }
+
+
+class CollectionLogMixin:
+    async def append(self, name: str, payload: Any) -> str:
+        """Append an entry to a log-kind collection; the actuator assigns a
+        ULID and timestamp. Returns the assigned entry id. Raises
+        RecordingDisabledError if the collection's recording flag is off."""
+        entry = await self.collection_append(name, payload)
+        if not entry:
+            raise RuntimeError("collection.append: actuator returned no entry")
+        return entry["id"]
+
+    async def append_entry(self, name: str, payload: Any) -> dict:
+        """Like `append` but returns the full LogEntry."""
+        entry = await self.collection_append(name, payload)
+        if not entry:
+            raise RuntimeError("collection.append: actuator returned no entry")
+        return entry
+
+    async def append_keyed(self, name: str, key: str, payload: Any) -> None:
+        """Annotate a keyed log (`log` preset, `id_strategy: by_field`):
+        appends `payload` with `key` stamped into the key field, as a fresh
+        append; same-key appends fold. Read the merged view with
+        `list_compacted`. See notes/DESIGN_LOG_ANNOTATION_PROJECTION.md."""
+        await self.collection_append_keyed(key, name, payload)
+
+    async def list_log(self, name: str, opts: dict | None = None) -> list[dict]:
+        """List log entries newest-first."""
+        entries, _ = await self.list_log_page(name, opts)
+        return entries
+
+    async def list_log_page(self, name: str, opts: dict | None = None) -> tuple[list[dict], int]:
+        """Like `list_log` but also returns the unfiltered total."""
+        records, total = await self.list_page(name, opts)
+        return [_record_to_log_entry(r) for r in records], total
+
+    async def get_log_entry(self, name: str, id: str) -> dict | None:
+        """One entry by id, or None. The RAW entry — on a keyed log use
+        `get_compacted` for a key's current state."""
+        rec = await self.get(name, id)
+        return _record_to_log_entry(rec) if rec else None
+
+    async def delete_log_entry(self, name: str, id: str) -> bool:
+        """Delete one entry by id. Returns whether it existed."""
+        return await self.delete(name, id)
+
+    async def set_collection_recording(self, name: str, enabled: bool) -> None:
+        """Toggle the recording flag on a log-kind collection. When False,
+        subsequent `append` calls raise RecordingDisabledError."""
+        await self.privacy_set_recording(enabled, name)
+
+    async def get_collection_recording(self, name: str) -> bool:
+        """The effective recording flag — the user override if set,
+        otherwise the manifest's `default_recording_enabled`."""
+        res = await self.privacy_get_recording(name)
+        return bool((res or {}).get("enabled", False))

branchkit/commands.py

@@ -0,0 +1,221 @@
+"""Command loading and authoring. Python twin of commands.{go,ts}.
+
+File layout:
+
+    $BRANCHKIT_PLUGIN_DIR/
+      commands.json     ← base commands (no context)
+      commands/         ← optional directory of context files
+        warp.json       ← context-scoped commands
+
+Commands in a context file inherit the context's requires_tags (merged
+with any on the command itself)."""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any
+
+# The actuator's command parser rejects an explicit JSON `null` for these
+# array fields (it accepts an array or an absent field). The builder
+# defaults them to [], but a spec from load_commands carries whatever the
+# file had — coerce None to [] before the wire. Mirrors Go's
+# normalizeCommandSpec.
+_COMMAND_SPEC_ARRAY_FIELDS = (
+    "requires_tags",
+    "sets_tags",
+    "clears_tags",
+    "sets_on_partial",
+    "variants",
+)
+
+
+def word(w: str) -> str:
+    """A literal spoken word."""
+    return w
+
+
+def one_of(*alts: str) -> list[str]:
+    """An alternatives slot: any of the given words matches, sharing one
+    action."""
+    return list(alts)
+
+
+def capture(name: str, collection: str) -> str:
+    """A list-capture token `<name:collection>` whose matched value binds
+    to `name`. An empty name uses the collection as the binding name."""
+    return f"<{name}:{collection}>" if name else f"<{collection}>"
+
+
+def text(name: str = "") -> str:
+    """A free-text capture token `<name:text>` (or `<text>`)."""
+    return f"<{name}:text>" if name else "<text>"
+
+
+class CommandBuilder:
+    """Accumulates a CommandSpec via chained setters; finish with build()."""
+
+    def __init__(self, slots: list):
+        self._spec: dict[str, Any] = {
+            "pattern": list(slots),
+            "cancels_bridge": False,
+            "requires_tags": [],
+            "sets_tags": [],
+            "clears_tags": [],
+            "sets_on_partial": [],
+            "display_sources": {},
+            "variants": [],
+        }
+
+    def action(self, type: str, params: dict | None = None) -> "CommandBuilder":
+        """Set the action fired on match. `type` is the action's type (a
+        built-in like "key" or a dotted plugin action); `params` are merged
+        into the action object."""
+        self._spec["action"] = {"type": type, **(params or {})}
+        return self
+
+    def requires_tags(self, *tags: str) -> "CommandBuilder":
+        self._spec["requires_tags"].extend(tags)
+        return self
+
+    def sets_tags(self, *tags: str) -> "CommandBuilder":
+        self._spec["sets_tags"].extend(tags)
+        return self
+
+    def clears_tags(self, *tags: str) -> "CommandBuilder":
+        self._spec["clears_tags"].extend(tags)
+        return self
+
+    def display_source(self, capture: str, collection: str) -> "CommandBuilder":
+        """Discovery-HUD display override for one capture: enumerate
+        `collection` in the HUD instead of the capture's matching
+        collection. Matching is untouched."""
+        self._spec["display_sources"][capture] = collection
+        return self
+
+    def sets_on_partial(self, *tags: str) -> "CommandBuilder":
+        self._spec["sets_on_partial"].extend(tags)
+        return self
+
+    def cancels_bridge(self) -> "CommandBuilder":
+        self._spec["cancels_bridge"] = True
+        return self
+
+    def discovery(self, mode: str) -> "CommandBuilder":
+        """Declare the command's prefix-discovery affordance ("prefix" or
+        "exclusive"). Valid only on a literal-prefix + single-tail-capture
+        pattern. See notes/DESIGN_DISCOVERABLE_PREFIX.md."""
+        self._spec["discovery"] = mode
+        return self
+
+    def category(self, c: str) -> "CommandBuilder":
+        self._spec["category"] = c
+        return self
+
+    def description(self, d: str) -> "CommandBuilder":
+        self._spec["description"] = d
+        return self
+
+    def build(self) -> dict:
+        return self._spec
+
+
+def command(*slots) -> CommandBuilder:
+    """Start a command builder with the given pattern slots."""
+    return CommandBuilder(list(slots))
+
+
+def _load_command_file(path: str) -> list[dict]:
+    """An ABSENT file is not an error — a plugin may ship only context
+    files, or none at all. Any other read failure propagates: swallowing
+    them is how an unreadable commands.json silently pushed zero
+    commands."""
+    try:
+        with open(path, encoding="utf-8") as f:
+            data = f.read()
+    except FileNotFoundError:
+        return []
+    except OSError as e:
+        raise RuntimeError(f"{path}: {e}") from e
+    return json.loads(data)
+
+
+def _load_context_file(path: str) -> list[dict]:
+    with open(path, encoding="utf-8") as f:
+        cf = json.load(f)
+    context_tags = ((cf.get("context") or {}).get("requires_tags")) or []
+    if not context_tags:
+        raise RuntimeError(f"{path}: missing or empty context.requires_tags")
+    commands = cf.get("commands") or []
+    return [_merge_requires_tags(cmd, context_tags) for cmd in commands]
+
+
+def _merge_requires_tags(cmd: dict, context_tags: list[str]) -> dict:
+    existing = cmd.get("requires_tags") or []
+    return {**cmd, "requires_tags": [*context_tags, *existing]}
+
+
+def load_commands() -> list[dict]:
+    """Load commands.json and any context files from commands/ WITHOUT
+    pushing — lets a plugin union file-authored static commands with built
+    dynamic ones and push them in a single push_command_specs call."""
+    plugin_dir = os.environ.get("BRANCHKIT_PLUGIN_DIR")
+    if not plugin_dir:
+        return []
+    raw: list[dict] = []
+    raw.extend(_load_command_file(os.path.join(plugin_dir, "commands.json")))
+    context_dir = os.path.join(plugin_dir, "commands")
+    try:
+        entries = sorted(e for e in os.listdir(context_dir) if e.endswith(".json"))
+    except OSError:
+        entries = []
+    for entry in entries:
+        raw.extend(_load_context_file(os.path.join(context_dir, entry)))
+    return raw
+
+
+def _normalize_command_spec(spec: dict) -> dict:
+    out = dict(spec)
+    for field in _COMMAND_SPEC_ARRAY_FIELDS:
+        if out.get(field) is None:
+            out[field] = []
+    return out
+
+
+async def push_commands(plugin) -> int:
+    """Load commands.json + context files and push them all via
+    commands.push. Returns the number of command variants registered."""
+    specs = load_commands()
+    if not specs:
+        return 0
+    return await push_command_specs(plugin, specs)
+
+
+async def push_command_specs(plugin, specs: list[dict]) -> int:
+    """Register a built/loaded set of commands via commands.push
+    (replace-per-plugin semantics). Returns the number of command variants
+    registered."""
+    resp = await plugin.call(
+        "commands.push", {"commands": [_normalize_command_spec(s) for s in specs]}
+    )
+    return (resp or {}).get("count") or 0
+
+
+async def push_command_group(plugin, group: str, specs: list[dict]) -> int:
+    """Register `specs` as a NAMED GROUP within this plugin's command set,
+    replacing only that group. Use whenever a plugin has more than one
+    command source — plain push_command_specs replaces the ENTIRE set, so
+    two sources pushing independently race. Returns the number of command
+    variants now active for the whole plugin."""
+    # Refused locally rather than sent: an empty group name is
+    # indistinguishable on the wire from an ungrouped push, which replaces
+    # EVERY group. A caller must not reach whole-set semantics by accident.
+    if not group:
+        raise ValueError(
+            "push_command_group: group name is required (use push_command_specs to replace the whole set)"
+        )
+    resp = await plugin.call(
+        "commands.push",
+        {"commands": [_normalize_command_spec(s) for s in specs], "group": group},
+    )
+    return (resp or {}).get("count") or 0