branchkit 0.1.0__tar.gz → 0.2.0__tar.gz

{branchkit-0.1.0 → branchkit-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: branchkit
-Version: 0.1.0
+Version: 0.2.0
 Summary: BranchKit plugin SDK for Python
 Author: BranchKit
 License-Expression: MIT

{branchkit-0.1.0 → branchkit-0.2.0}/branchkit/__init__.py

@@ -23,6 +23,7 @@ from . import proxy as _proxy
 _proxy.install_proxy_from_env()
 
 from .plugin import (
+    DetachedError,
     PluginCore,
     RecordingDisabledError,
     RpcCallError,
@@ -32,6 +33,7 @@ from .plugin import (
     plugin_data_dir,
     plugin_dir,
 )
+from .actor import acting_for, get_current_actor
 from .collection import CollectionMixin, list_opts, scope_collection, scope_group
 from .collection_log import CollectionLogMixin, log_list_opts
 from .debug import DebugMixin
@@ -58,6 +60,7 @@ from .settings_route import method_post, method_url
 from .ui import (
     Expr,
     args,
+    js,
     confirm_button,
     expr,
     input_value,

branchkit-0.2.0/branchkit/actor.py

@@ -0,0 +1,56 @@
+# The actor label — who this plugin is acting *on behalf of*.
+#
+# A host-shaped plugin runs things the platform does not model: a scripting
+# host runs script files, the browser plugin fronts an extension, an
+# ambassador fronts an external app. Every platform call it makes is its own,
+# over its own session, so audit rows, collection records, and events can name
+# only the plugin. `acting_for` stamps the finer-grained label on the outbound
+# envelope, and the platform carries it into what it writes.
+#
+# Observability only, by construction. The platform never consults the label
+# for any decision — it cannot, because the host supplies it from inside its
+# own process, so a lying host would only lie about a label it already had the
+# grant to act under. Setting it widens nothing and narrows nothing; it makes
+# the trail readable. Per-hosted-thing ENFORCEMENT would need real delegated
+# identities, which is a different (unbuilt) feature.
+#
+# Scoped with a `contextvars.ContextVar`, exactly like the ambient inbound
+# correlation: hosted things interleave across tasks, and a module global
+# would let one hosted thing's label ride another's calls.
+
+from contextlib import contextmanager
+from contextvars import ContextVar
+
+_current: ContextVar[str] = ContextVar("branchkit_actor", default="")
+
+
+def set_actor(actor: str | None):
+    """Make `actor` ambient for the current context. Returns a token for
+    `reset_actor`. A falsy actor sets the empty ambient — "no label"."""
+    return _current.set(actor or "")
+
+
+def reset_actor(token) -> None:
+    _current.reset(token)
+
+
+def get_current_actor() -> str:
+    """The actor label outbound calls currently carry, or "" if none."""
+    return _current.get()
+
+
+@contextmanager
+def acting_for(actor: str | None):
+    """Stamp `actor` on every RPC made inside the block.
+
+        with acting_for("headphones.py"):
+            await plugin.dispatch(action)
+
+    Nested blocks restore the outer label on exit, so one hosted thing
+    invoking another leaves the trail intact.
+    """
+    token = set_actor(actor)
+    try:
+        yield
+    finally:
+        reset_actor(token)

{branchkit-0.1.0 → branchkit-0.2.0}/branchkit/closed_vocab_gen.py

@@ -9,16 +9,16 @@ from typing import NotRequired, TypedDict
 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:
+# `consumes.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_PREVENT_SYSTEM_SLEEP = "prevent_system_sleep"
+EFFECT_SIGNAL_CLIPBOARD_IN_USE = "signal_clipboard_in_use"
 EFFECT_SIGNAL_RECORDING_ACTIVE = "signal_recording_active"
 EFFECT_SUPPRESS_HUDS = "suppress_huds"
 EFFECT_SUPPRESS_KEYBINDS = "suppress_keybinds"
 EFFECT_SUPPRESS_NOTIFICATIONS = "suppress_notifications"
+EFFECT_SUPPRESS_VOICE_COMMANDS = "suppress_voice_commands"
 
 # The full closed-vocabulary sets.
 KNOWN_INPUT_DIRECTIVES = (
@@ -27,13 +27,13 @@ KNOWN_INPUT_DIRECTIVES = (
 
 KNOWN_EFFECTS = (
     "disable_screen_dim",
-    "mute_audio_to_other_apps",
-    "pause_microphone_indicator",
-    "prevent_focus_steal",
+    "prevent_system_sleep",
+    "signal_clipboard_in_use",
     "signal_recording_active",
     "suppress_huds",
     "suppress_keybinds",
     "suppress_notifications",
+    "suppress_voice_commands",
 )
 
 # ERROR_KIND_* are the closed-vocabulary `kind` values the actuator puts
@@ -89,7 +89,9 @@ KNOWN_ERROR_KINDS = (
 FaultData = TypedDict("FaultData", {
     "kind": str,
     "collection": NotRequired[str],
+    "consent": NotRequired[str],
     "detail": NotRequired[str],
     "id": NotRequired[str],
     "op": NotRequired[str],
+    "privilege": NotRequired[str],
 })

{branchkit-0.1.0 → branchkit-0.2.0}/branchkit/collection.py

@@ -70,9 +70,88 @@ class CollectionMixin:
         return rec if isinstance(rec, dict) else None
 
     async def list(self, name: str, opts: dict | None = None) -> list[dict]:
+        """Read ONE PAGE of records.
+
+        Omitting `opts` does NOT mean "every record": the platform applies a
+        default limit when the caller supplies none, so a large collection
+        comes back truncated, and this method discards `total` so it cannot
+        tell you that happened.
+
+        Choose deliberately: some records -> `list` with an explicit `limit`;
+        every record -> `list_all`; a page plus the real count -> `list_page`.
+        """
         res = await self.collection_list(name, opts)
         return (res or {}).get("records") or []
 
+    async def list_all(self, name: str) -> list[dict]:
+        """Read EVERY record, defeating the platform's default list limit.
+
+        Use this when the read has to be exhaustive - clearing a collection,
+        reconciling against it, counting it. `list` returns one page and
+        discards `total`, so a caller using it cannot tell a complete read
+        from a capped one; that is a quiet correctness bug wherever
+        completeness was assumed.
+
+        Prefer `list` with an explicit `limit` when you only need some
+        records: this one is deliberately unbounded.
+        """
+        return await self._list_exhaustive(name, compacted=False)
+
+    async def list_all_compacted(self, name: str) -> list[dict]:
+        """`list_all` over the compacted-changelog projection - every folded
+        record, one per key. A keyed log with more live keys than the cap
+        otherwise folds to a view its reader believes is whole."""
+        return await self._list_exhaustive(name, compacted=True)
+
+    async def _list_exhaustive(self, name: str, compacted: bool) -> list[dict]:
+        """Reads a collection completely, re-reading while it grows.
+
+        Normally two round trips, not a cursor walk: `total` comes back with
+        the first page, so the second read is bounded exactly. Cursor paging
+        would be wrong anyway on contribution-keyed storage, where `cursor` is
+        a no-op.
+
+        The probe passes an EXPLICIT limit rather than omitting one. Reading
+        with no limit to discover `total` would trip the platform's
+        default-limit warning on every call - this helper would manufacture
+        the exact noise that warning exists to surface, burying real
+        occurrences underneath it.
+
+        `total` is the FOLDED count when compacted, so the short-circuit is a
+        real one on both projections rather than a guaranteed miss.
+        """
+        first_page = 1000
+
+        async def page(limit: int) -> tuple[list[dict], int]:
+            opts: dict = {"limit": limit}
+            if compacted:
+                opts["compacted"] = True
+            return await self.list_page(name, opts)
+
+        # Re-reads until the page covers `total`, because `total` is
+        # observed on the read that returns it and the collection can grow
+        # between reads. Taking the first `total` on faith would hand back a
+        # short result reported as complete - the same "mirror declares
+        # itself Ready over a truncated read" this helper exists to prevent,
+        # just with a narrower window: one write landing mid-refresh is
+        # enough.
+        #
+        # Bounded rather than unbounded: a collection written faster than it
+        # can be read is not a condition to spin on, and a caller waiting on
+        # a mirror refresh should get an answer. Practically it settles on
+        # the second read.
+        max_passes = 5
+        limit = first_page
+        for _ in range(max_passes):
+            records, total = await page(limit)
+            if len(records) >= total:
+                return records
+            limit = total
+        raise RuntimeError(
+            f"collection {name!r} kept growing across {max_passes} exhaustive "
+            "reads; read it with an explicit limit and page with cursor instead"
+        )
+
     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."""
@@ -120,7 +199,7 @@ class CollectionMixin:
         ``{"put": n, "deleted": n, "skipped": n}``.
 
         Scope is required and never inferred — pass `scope_collection()` or
-        `scope_group(...)`. See notes/DESIGN_COLLECTION_REPLACE.md."""
+        `scope_group(...)`. See docs/design/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.

{branchkit-0.1.0 → branchkit-0.2.0}/branchkit/collection_log.py

@@ -62,7 +62,7 @@ class CollectionLogMixin:
         """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."""
+        `list_compacted`. See docs/design/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]:

{branchkit-0.1.0 → branchkit-0.2.0}/branchkit/commands.py

@@ -69,9 +69,10 @@ class CommandBuilder:
 
     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 {})}
+        built-in like "key" or a dotted plugin action); `params` nest under
+        the action object's `params` key — one dialect, see
+        DESIGN_ONE_PARAMS_DIALECT.md."""
+        self._spec["action"] = {"type": type, "params": params} if params else {"type": type}
         return self
 
     def requires_tags(self, *tags: str) -> "CommandBuilder":
@@ -102,9 +103,12 @@ class CommandBuilder:
         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."""
+        """Declare the command's prefix-discovery affordance ("prefix",
+        "exclusive", or "select" — select points at entries via
+        platform-assigned alphabet codewords instead of their names). Valid
+        only on a literal-prefix + single-tail-capture pattern. See
+        docs/design/DESIGN_DISCOVERABLE_PREFIX.md and
+        DESIGN_SELECTION_PRIMITIVE.md."""
         self._spec["discovery"] = mode
         return self
 

{branchkit-0.1.0 → branchkit-0.2.0}/branchkit/contracts_gen.py

@@ -59,6 +59,7 @@ METHOD_INPUT_DOUBLE_CLICK = "input.double_click"  # since 0.1.0
 METHOD_INPUT_DRAG = "input.drag"  # since 0.1.0
 METHOD_INPUT_LIST_INPUT_SOURCES = "input.list_input_sources"  # since 0.1.0
 METHOD_INPUT_MOUSE_BUTTON = "input.mouse_button"  # since 0.1.0
+METHOD_INPUT_PARSE_KEY_EVENT = "input.parse_key_event"  # since 0.1.0
 METHOD_INPUT_PRESS_KEY = "input.press_key"  # since 0.1.0
 METHOD_INPUT_RAW_KEY = "input.raw_key"  # since 0.1.0
 METHOD_INPUT_RIGHT_CLICK = "input.right_click"  # since 0.1.0
@@ -67,7 +68,6 @@ METHOD_INPUT_SELECT_ALL = "input.select_all"  # since 0.1.0
 METHOD_INPUT_SWITCH_INPUT_SOURCE = "input.switch_input_source"  # since 0.1.0
 METHOD_INPUT_TRIPLE_CLICK = "input.triple_click"  # since 0.1.0
 METHOD_INPUT_TYPE_TEXT = "input.type_text"  # since 0.1.0
-METHOD_KEY_NAMES_SET = "key_names.set"  # since 0.1.0
 METHOD_KEYBINDS_REGISTER = "keybinds.register"  # since 0.1.0
 METHOD_MODEL_DELETE = "model.delete"  # since 0.1.0
 METHOD_NATIVE_ACCENT_COLOR = "native.accent_color"  # since 0.1.0
@@ -587,9 +587,15 @@ METHOD_PIPELINES_STOP = "pipelines.stop"  # since 0.1.0
 METHOD_PIPELINES_WARM = "pipelines.warm"  # since 0.1.0
 METHOD_PLUGIN_DATA_EXPORT = "plugin.data.export"  # since 0.1.0
 METHOD_PLUGIN_DEBUG = "plugin.debug"  # since 0.1.0
+METHOD_PLUGIN_REPORT_HEALTH = "plugin.report_health"  # since 0.1.0
 METHOD_PRIVACY_GET_RECORDING = "privacy.get_recording"  # stable, since 0.1.0
 METHOD_PRIVACY_SET_RECORDING = "privacy.set_recording"  # stable, since 0.1.0
+METHOD_PRIVILEGES_LIST = "privileges.list"  # since 0.1.0
+METHOD_PRIVILEGES_RELINQUISH = "privileges.relinquish"  # since 0.1.0
+METHOD_PRIVILEGES_REQUEST = "privileges.request"  # since 0.1.0
 METHOD_RECOGNITION_BIAS_APPLY = "recognition.bias.apply"  # since 0.1.0
+METHOD_RECOGNITION_BIAS_GET = "recognition.bias.get"  # since 0.1.0
+METHOD_RECOGNITION_BIAS_SET = "recognition.bias.set"  # since 0.1.0
 METHOD_RECOGNITION_REDECODE = "recognition.redecode"  # since 0.1.0
 METHOD_SELECTION_PICK = "selection.pick"  # since 0.1.0
 METHOD_SELECTION_SET = "selection.set"  # since 0.1.0
@@ -609,11 +615,12 @@ METHOD_TRIAL_ENTER_CONTEXT = "trial.enter_context"  # since 0.1.0
 METHOD_TRIAL_REGISTER_FIXTURE = "trial.register_fixture"  # since 0.1.0
 METHOD_TRIAL_RESOLVE_SAMPLES = "trial.resolve_samples"  # since 0.1.0
 METHOD_VOCABULARY_COMMIT = "vocabulary.commit"  # since 0.1.0
+METHOD_WIRING_DESCRIBE = "wiring.describe"  # since 0.1.0
 
 # RPC method names: actuator → plugin (use with plugin.handle()).
 HOOK_ON_ACTION = "on_action"  # since 0.1.0
 HOOK_ON_COMMANDS_CHANGED = "on_commands_changed"  # since 0.1.0
-HOOK_RENDER_HUD = "render_hud"  # since 0.1.0
+HOOK_ON_TRANSCRIPT = "on_transcript"  # since 0.1.0
 HOOK_RENDER_SETTINGS = "render_settings"  # since 0.1.0
 HOOK_TRIAL_APPLY_FIXTURE = "trial_apply_fixture"  # since 0.1.0
 HOOK_TRIAL_RELEASE_FIXTURE = "trial_release_fixture"  # since 0.1.0
@@ -630,6 +637,7 @@ EVENT_COLLECTION_UPDATED = "_platform.collection.updated"
 EVENT_DISCOVERY_CLOSED = "_platform.discovery.closed"
 EVENT_DISPLAY_CHANGED = "_platform.display.changed"
 EVENT_EFFECT_DISPLACED = "_platform.effect.displaced"
+EVENT_EFFECT_OWNERSHIP_CHANGED = "_platform.effect.ownership_changed"
 EVENT_HID_CONNECTED = "_platform.hid.connected"
 EVENT_HID_DISCONNECTED = "_platform.hid.disconnected"
 EVENT_HID_INPUT = "_platform.hid.input"
@@ -649,6 +657,7 @@ EVENT_PLUGIN_DEGRADED = "_platform.plugin.degraded"
 EVENT_PLUGIN_DISABLED = "_platform.plugin.disabled"
 EVENT_PLUGIN_ENABLED = "_platform.plugin.enabled"
 EVENT_POWER_CHANGED = "_platform.power.changed"
+EVENT_PRIVILEGE_GRANTED = "_platform.privilege.granted"
 EVENT_SELECTION_PICKED = "_platform.selection.picked"
 EVENT_SYSTEM_DID_WAKE = "_platform.system.did_wake"
 EVENT_SYSTEM_WILL_SLEEP = "_platform.system.will_sleep"

{branchkit-0.1.0 → branchkit-0.2.0}/branchkit/debug.py

@@ -1,7 +1,7 @@
 """Per-plugin leveled log façade over `plugin.debug` (the RPC method).
 Python twin of debug.{go,ts}. Lines land in
 `<app_support>/plugin-logs/<pluginID>.log`; warn/error cross-post to
-actuator.log. See notes/DESIGN_PLUGIN_LOG_LEVELS.md."""
+actuator.log. See docs/design/DESIGN_PLUGIN_LOG_LEVELS.md."""
 
 from __future__ import annotations
 

{branchkit-0.1.0 → branchkit-0.2.0}/branchkit/effects.py

@@ -1,5 +1,5 @@
 """Capability-mechanism helpers (effects). Python twin of effects.{go,ts}.
-See notes/DESIGN_CAPABILITY_MECHANISM.md."""
+See docs/design/DESIGN_CAPABILITY_MECHANISM.md."""
 
 from __future__ import annotations
 
@@ -15,7 +15,7 @@ def _optional_str(v) -> str | None:
 class EffectsMixin:
     async def assert_effect(self, name: str) -> dict:
         """Declare this plugin is asserting `name` (which must be declared
-        in the manifest's `provides.effects[*].asserts`). Returns
+        in the manifest's `consumes.effects[*].asserts`). Returns
         ``{"granted", "already_held", "displaced", "enforced"}``."""
         res = await self.effects_assert(name)
         return {

{branchkit-0.1.0 → branchkit-0.2.0}/branchkit/harness.py

@@ -275,7 +275,11 @@ def find_harness_binary() -> str:
     env = os.environ.get("BRANCHKIT_TEST_HARNESS")
     if env:
         return env
+    # The installed app ships the harness in its Resources; the cargo
+    # target paths serve app-repo checkouts.
     candidates = [
+        "/Applications/BranchKit.app/Contents/Resources/branchkit-test-harness",
+        os.path.expanduser("~/Applications/BranchKit.app/Contents/Resources/branchkit-test-harness"),
         "target/debug/branchkit-test-harness",
         "target/release/branchkit-test-harness",
         "../target/debug/branchkit-test-harness",
@@ -291,6 +295,7 @@ def find_harness_binary() -> str:
     if found:
         return found
     raise OSError(
-        "harness: cannot find branchkit-test-harness binary. "
-        "Set BRANCHKIT_TEST_HARNESS or run 'cargo build -p branchkit-test-harness'"
+        "harness: cannot find branchkit-test-harness binary. It ships inside "
+        "BranchKit.app (Contents/Resources); install the app, or set "
+        "BRANCHKIT_TEST_HARNESS to a harness binary."
     )

{branchkit-0.1.0 → branchkit-0.2.0}/branchkit/listen.py

@@ -9,7 +9,7 @@ network namespace, where a self-bound 127.0.0.1 is a private dead
 loopback — the inherited host-loopback listener is the only reachable
 surface. CPython serves an inherited fd natively
 (`socket.socket(fileno=...)`), so unlike TS there is no two-runtime
-dance. See the actuator's notes/DESIGN_SANDBOX_LOOPBACK_FDPASS.md."""
+dance. See the actuator's docs/design/DESIGN_SANDBOX_LOOPBACK_FDPASS.md."""
 
 from __future__ import annotations
 

{branchkit-0.1.0 → branchkit-0.2.0}/branchkit/log_events_gen.py

@@ -2,7 +2,7 @@
 # Run: just contracts
 #
 # BranchKit observability bus — closed log-event vocabulary.
-# See notes/DESIGN_OBSERVABILITY_BUS.md for the architectural contract.
+# See docs/design/DESIGN_OBSERVABILITY_BUS.md for the architectural contract.
 
 from typing import TypedDict
 
@@ -14,6 +14,8 @@ LOG_EVENT_CAPTURE_PROGRESS = "capture.progress"
 LOG_EVENT_COMMAND_MATCH_DECISION = "command.match_decision"
 LOG_EVENT_COMMAND_MATCHED = "command.matched"
 LOG_EVENT_COMMAND_NO_MATCH = "command.no_match"
+LOG_EVENT_CONSENT_DECISION = "consent.decision"
+LOG_EVENT_CONSENT_PRIVILEGED_OP = "consent.privileged_op"
 LOG_EVENT_DIAGNOSTIC_MESSAGE = "diagnostic.message"
 LOG_EVENT_DISPATCH_ACTION_DISPATCHED = "dispatch.action_dispatched"
 LOG_EVENT_DISPATCH_ACTION_PANICKED = "dispatch.action_panicked"
@@ -84,6 +86,8 @@ LOG_EVENT_REGISTRY: dict[str, LogEventMeta] = {
     "command.match_decision": {"name": "command.match_decision", "summary": "Diagnostic snapshot of the matcher's tiebreaker choice — which category won, which gates were active, whether a gated Partial was suppressed.", "since": "0.1.0", "source": "dispatch", "severity": "debug", "redaction": "none"},
     "command.matched": {"name": "command.matched", "summary": "Speech recognition produced a match against a registered command.", "since": "0.1.0", "source": "dispatch", "severity": "info", "redaction": "none"},
     "command.no_match": {"name": "command.no_match", "summary": "Speech input did not match any registered command.", "since": "0.1.0", "source": "dispatch", "severity": "debug", "redaction": "none"},
+    "consent.decision": {"name": "consent.decision", "summary": "A consent decision on any axis (privilege, dispatch, event subscription, collection read/write, effect, trusted author): granted (always/once), denied, dismissed, revoked, or reconciled by an update — with the surface that produced it. Audit-eligible.", "since": "0.1.0", "source": "plugins", "severity": "info", "redaction": "none"},
+    "consent.privileged_op": {"name": "consent.privileged_op", "summary": "A plugin invoked (or was refused) an operation gated on a dangerous privilege. Audit-eligible.", "since": "0.1.0", "source": "plugins", "severity": "info", "redaction": "none"},
     "diagnostic.message": {"name": "diagnostic.message", "summary": "Catch-all for ad-hoc operational text that doesn't fit a typed variant.", "since": "0.1.0", "source": "generic", "severity": "debug", "redaction": "none"},
     "dispatch.action_dispatched": {"name": "dispatch.action_dispatched", "summary": "An action entered the dispatch pipeline.", "since": "0.1.0", "source": "dispatch", "severity": "debug", "redaction": "none"},
     "dispatch.action_panicked": {"name": "dispatch.action_panicked", "summary": "A dispatch handler panicked. Process likely degraded; investigate.", "since": "0.1.0", "source": "dispatch", "severity": "error", "redaction": "none"},
@@ -104,7 +108,7 @@ LOG_EVENT_REGISTRY: dict[str, LogEventMeta] = {
     "native.window_skipped": {"name": "native.window_skipped", "summary": "World poller skipped a non-standard window (debug-level).", "since": "0.1.0", "source": "native", "severity": "debug", "redaction": "none"},
     "native.world_poller_event": {"name": "native.world_poller_event", "summary": "World poller lifecycle event (started, seeded, batch processed, idle).", "since": "0.1.0", "source": "native", "severity": "debug", "redaction": "none"},
     "operation.completed": {"name": "operation.completed", "summary": "An operation handler completed execution.", "since": "0.1.0", "source": "dispatch", "severity": "debug", "redaction": "none"},
-    "plugin.degraded": {"name": "plugin.degraded", "summary": "A managed plugin's RPC channel hit the consecutive-timeout threshold and was marked degraded.", "since": "0.1.0", "source": "plugins", "severity": "warn", "redaction": "none"},
+    "plugin.degraded": {"name": "plugin.degraded", "summary": "A plugin is running but not fully working — either its RPC channel hit the consecutive-timeout threshold (reason absent), or the plugin reported the fault itself via plugin.report_health (reason present).", "since": "0.1.0", "source": "plugins", "severity": "warn", "redaction": "none"},
     "plugin.diagnostic": {"name": "plugin.diagnostic", "summary": "A plugin emitted a warn- or error-level diagnostic via plugin.debug; cross-posted to actuator.log so plugin-level failures interleave with the actuator's view of dispatch / coordination.", "since": "0.2.0", "source": "plugins", "severity": "warn", "redaction": "none"},
     "plugin.exited": {"name": "plugin.exited", "summary": "A managed plugin process exited (clean or crashed).", "since": "0.1.0", "source": "plugins", "severity": "info", "redaction": "none"},
     "plugin.lifecycle_op": {"name": "plugin.lifecycle_op", "summary": "A plugin lifecycle operation (install, uninstall, update, reload, hot-reload, enable, disable).", "since": "0.1.0", "source": "plugins", "severity": "info", "redaction": "none"},

{branchkit-0.1.0 → branchkit-0.2.0}/branchkit/methods_gen.py

@@ -60,6 +60,7 @@ from .contracts_gen import (
     METHOD_INPUT_DRAG,
     METHOD_INPUT_LIST_INPUT_SOURCES,
     METHOD_INPUT_MOUSE_BUTTON,
+    METHOD_INPUT_PARSE_KEY_EVENT,
     METHOD_INPUT_PRESS_KEY,
     METHOD_INPUT_RAW_KEY,
     METHOD_INPUT_RIGHT_CLICK,
@@ -69,7 +70,6 @@ from .contracts_gen import (
     METHOD_INPUT_TRIPLE_CLICK,
     METHOD_INPUT_TYPE_TEXT,
     METHOD_KEYBINDS_REGISTER,
-    METHOD_KEY_NAMES_SET,
     METHOD_MODEL_DELETE,
     METHOD_NATIVE_ACCENT_COLOR,
     METHOD_NATIVE_ACCESSIBILITY_DISPLAY_INVERT,
@@ -588,9 +588,15 @@ from .contracts_gen import (
     METHOD_PIPELINES_WARM,
     METHOD_PLUGIN_DATA_EXPORT,
     METHOD_PLUGIN_DEBUG,
+    METHOD_PLUGIN_REPORT_HEALTH,
     METHOD_PRIVACY_GET_RECORDING,
     METHOD_PRIVACY_SET_RECORDING,
+    METHOD_PRIVILEGES_LIST,
+    METHOD_PRIVILEGES_RELINQUISH,
+    METHOD_PRIVILEGES_REQUEST,
     METHOD_RECOGNITION_BIAS_APPLY,
+    METHOD_RECOGNITION_BIAS_GET,
+    METHOD_RECOGNITION_BIAS_SET,
     METHOD_RECOGNITION_REDECODE,
     METHOD_SELECTION_PICK,
     METHOD_SELECTION_SET,
@@ -610,6 +616,7 @@ from .contracts_gen import (
     METHOD_TRIAL_REGISTER_FIXTURE,
     METHOD_TRIAL_RESOLVE_SAMPLES,
     METHOD_VOCABULARY_COMMIT,
+    METHOD_WIRING_DESCRIBE,
 )
 
 if TYPE_CHECKING:
@@ -662,9 +669,9 @@ if TYPE_CHECKING:
         HidElementEntry,
         InputClipboardReadFormatResponse,
         InputClipboardReadResponse,
+        InputParseKeyEventResponse,
         InputSource,
         InstalledApp,
-        KeyNamesSetResponse,
         KeybindsRegisterResponse,
         ListOpts,
         ListeningPort,
@@ -952,8 +959,13 @@ if TYPE_CHECKING:
         PluginDataExportResponse,
         PrinterInfo,
         PrivacyGetRecordingResponse,
+        PrivilegeStatusEntry,
+        PrivilegesRelinquishResponse,
+        PrivilegesRequestResponse,
         ProcessInfo,
         RecognitionBiasApplyResponse,
+        RecognitionBiasGetResponse,
+        RecognitionBiasSetResponse,
         RecognitionRedecodeResponse,
         RedecodeItem,
         ReminderItem,
@@ -974,6 +986,7 @@ if TYPE_CHECKING:
         UsbDevice,
         WindowDetail,
         WindowFrame,
+        WiringCollection,
         WorldModel,
     )
 
@@ -1226,14 +1239,10 @@ class MethodsMixin:
     async def discovery_closed(self) -> None:
         await self.call(METHOD_DISCOVERY_CLOSED)
 
-    async def dispatch(self, action: Any, session_id: str | None = None, trace_id: str | None = None) -> DispatchResponse:
+    async def dispatch(self, action: Any) -> DispatchResponse:
         params: dict[str, Any] = {
             "action": action,
         }
-        if session_id is not None:
-            params["session_id"] = session_id
-        if trace_id is not None:
-            params["trace_id"] = trace_id
         result = await self.call(METHOD_DISPATCH, params)
         return result
 
@@ -1420,6 +1429,24 @@ class MethodsMixin:
             params["button"] = button
         await self.call(METHOD_INPUT_MOUSE_BUTTON, params)
 
+    async def input_parse_key_event(self, alt: bool | None = None, code: str | None = None, ctrl: bool | None = None, key: str | None = None, meta: bool | None = None, shift: bool | None = None) -> InputParseKeyEventResponse:
+        params: dict[str, Any] = {
+        }
+        if alt is not None:
+            params["alt"] = alt
+        if code is not None:
+            params["code"] = code
+        if ctrl is not None:
+            params["ctrl"] = ctrl
+        if key is not None:
+            params["key"] = key
+        if meta is not None:
+            params["meta"] = meta
+        if shift is not None:
+            params["shift"] = shift
+        result = await self.call(METHOD_INPUT_PARSE_KEY_EVENT, params)
+        return result
+
     async def input_press_key(self, code: int | None = None, modifiers: list[str] | None = None, name: str | None = None) -> None:
         params: dict[str, Any] = {
         }
@@ -1482,14 +1509,6 @@ class MethodsMixin:
         }
         await self.call(METHOD_INPUT_TYPE_TEXT, params)
 
-    async def key_names_set(self, names: dict[str, int] | None = None) -> KeyNamesSetResponse:
-        params: dict[str, Any] = {
-        }
-        if names is not None:
-            params["names"] = names
-        result = await self.call(METHOD_KEY_NAMES_SET, params)
-        return result
-
     async def keybinds_register(self, snapshot: Any) -> KeybindsRegisterResponse:
         params: dict[str, Any] = {
             "snapshot": snapshot,
@@ -4184,10 +4203,11 @@ class MethodsMixin:
         result = await self.call(METHOD_PIPELINES_GRAMMAR, params)
         return result
 
-    async def pipelines_inject(self, event_type: str, name: str, data: Any | None = None) -> PipelinesInjectResponse:
+    async def pipelines_inject(self, event_type: str, name: str, stage: str, data: Any | None = None) -> PipelinesInjectResponse:
         params: dict[str, Any] = {
             "event_type": event_type,
             "name": name,
+            "stage": stage,
         }
         if data is not None:
             params["data"] = data
@@ -4247,6 +4267,14 @@ class MethodsMixin:
             params["tag"] = tag
         await self.call(METHOD_PLUGIN_DEBUG, params)
 
+    async def plugin_report_health(self, degraded: bool, reason: str | None = None) -> None:
+        params: dict[str, Any] = {
+            "degraded": degraded,
+        }
+        if reason is not None:
+            params["reason"] = reason
+        await self.call(METHOD_PLUGIN_REPORT_HEALTH, params)
+
     async def privacy_get_recording(self, name: str) -> PrivacyGetRecordingResponse:
         params: dict[str, Any] = {
             "name": name,
@@ -4261,6 +4289,26 @@ class MethodsMixin:
         }
         await self.call(METHOD_PRIVACY_SET_RECORDING, params)
 
+    async def privileges_list(self) -> list[PrivilegeStatusEntry]:
+        result = await self.call(METHOD_PRIVILEGES_LIST)
+        return (result or {}).get("privileges") or []
+
+    async def privileges_relinquish(self, privilege: str) -> PrivilegesRelinquishResponse:
+        params: dict[str, Any] = {
+            "privilege": privilege,
+        }
+        result = await self.call(METHOD_PRIVILEGES_RELINQUISH, params)
+        return result
+
+    async def privileges_request(self, privilege: str, reason: str | None = None) -> PrivilegesRequestResponse:
+        params: dict[str, Any] = {
+            "privilege": privilege,
+        }
+        if reason is not None:
+            params["reason"] = reason
+        result = await self.call(METHOD_PRIVILEGES_REQUEST, params)
+        return result
+
     async def recognition_bias_apply(self, strength: float, force: bool | None = None) -> RecognitionBiasApplyResponse:
         params: dict[str, Any] = {
             "strength": strength,
@@ -4270,6 +4318,20 @@ class MethodsMixin:
         result = await self.call(METHOD_RECOGNITION_BIAS_APPLY, params)
         return result
 
+    async def recognition_bias_get(self) -> RecognitionBiasGetResponse:
+        result = await self.call(METHOD_RECOGNITION_BIAS_GET)
+        return result
+
+    async def recognition_bias_set(self, enabled: bool | None = None, strength: float | None = None) -> RecognitionBiasSetResponse:
+        params: dict[str, Any] = {
+        }
+        if enabled is not None:
+            params["enabled"] = enabled
+        if strength is not None:
+            params["strength"] = strength
+        result = await self.call(METHOD_RECOGNITION_BIAS_SET, params)
+        return result
+
     async def recognition_redecode(self, items: list["RedecodeItem"], model: str, stage: str, max_active: int | None = None) -> RecognitionRedecodeResponse:
         params: dict[str, Any] = {
             "items": items,
@@ -4429,3 +4491,7 @@ class MethodsMixin:
 
     async def vocabulary_commit(self) -> None:
         await self.call(METHOD_VOCABULARY_COMMIT)
+
+    async def wiring_describe(self) -> list[WiringCollection]:
+        result = await self.call(METHOD_WIRING_DESCRIBE)
+        return (result or {}).get("collections") or []