bitwig-agent 0.1.1__py3-none-any.whl

bitwig_agent/__init__.py

@@ -0,0 +1,2 @@
+"""A thin bridge; the Bitwig host owns state and operation outcomes."""
+

bitwig_agent/__main__.py

@@ -0,0 +1,6 @@
+"""Run the stdio MCP server with python -m bitwig_agent."""
+from .server import main
+
+
+if __name__ == "__main__":
+    main()

bitwig_agent/catalog.py

@@ -0,0 +1,101 @@
+"""The public domain catalog; no transport, MCP runtime or host initialization."""
+
+from dataclasses import dataclass
+from typing import Any
+
+from bitwig_agent import schema
+
+
+@dataclass(frozen=True)
+class ToolSpec:
+    model: type[schema.StatusArgs]
+    description: str
+    read_only: bool
+    examples: tuple[dict[str, Any], ...]
+
+    def describe(self) -> dict[str, Any]:
+        return {"description": self.description, "readOnly": self.read_only,
+                "inputSchema": self.model.model_json_schema(), "examples": list(self.examples)}
+
+
+# Example UUIDs are placeholders: discover real targets with tracks.list first.
+TRACK = "12345678-1234-1234-1234-123456789abc"
+TARGET = {"trackId": TRACK, "deviceIndex": 0, "expectedDeviceName": "Poly Grid"}
+LAYER_PARENT = {"trackId": TRACK, "deviceIndex": 0, "expectedDeviceName": "Instrument Layer"}
+LAYER_TARGET = {"parent": LAYER_PARENT, "layerId": "abcdef01-2345-6789-abcd-0123456789ab",
+                "childDeviceIndex": 0, "expectedChildDeviceName": "Polymer",
+                "discoveryToken": "from-devices.layers.list"}
+CLIP = {"trackId": TRACK, "slotIndex": 0}
+NOTE_WINDOW = {**CLIP, "channel": 0, "stepSizeBeats": 0.25, "startStep": 0,
+               "steps": 16, "pitchStart": 0, "pitchCount": 128}
+
+
+def tool(model, description, read_only, *examples):
+    return ToolSpec(model, description, read_only, examples or ({},))
+
+
+TOOLS: dict[str, ToolSpec] = {
+    "status": tool(schema.StatusArgs, "Observe project/transport state, not proof of audio or persistence.", True),
+    "capabilities": tool(schema.StatusArgs, "Discover implemented host methods, bounded windows, units and unsupported interfaces. Local CLI list/describe work even without Bitwig; this method queries the running extension.", True),
+    "tracks.list": tool(schema.StatusArgs, "Discover real track UUIDs in the flat bounded track window. All our track/device/clip/channel indices are zero-based. Inspect window completeness before choosing targets; example UUIDs are not real targets.", True),
+    "tracks.get": tool(schema.DeviceArgs, "Read one track's mix state and bounded sends by UUID from tracks.list. Values explicitly named Normalized are in 0..1, not dB. Fields may be null after target changes; inspect readable, observationsComplete and sendObservationsComplete rather than treating partial observations as current values.", True, {"trackId": TRACK}),
+    "tracks.set": tool(schema.TrackSetArgs, "Set only differing fields from a fresh tracks.get snapshot, by UUID; omitted fields stay unchanged. Inspect completion and each fields entry's verification. A redundant same-value write on a rebound proxy may remain unknown without a fresh callback; never automatically retry unknown. Values named Normalized are 0..1, not dB.", False, {"trackId": TRACK, "mute": True}),
+    "tracks.select": tool(schema.DeviceArgs, "Explicitly select a track in the host UI by discovered UUID. Selection is a UI side effect; reads do not require it.", False, {"trackId": TRACK}),
+    "tracks.create": tool(schema.TrackCreateArgs, "Create and name a track. position=-1 appends; otherwise a zero-based main-track index for audio/instrument, effect-list index for effect. Inspect creation identity/verification before using the new track. An unresolved creation quarantines further creates for this extension instance (unresolved_creation); inspect actual state, never blindly retry or reset to bypass ambiguity.", False, {"type": "instrument", "position": -1, "name": "Agent Sketch"}),
+    "transport.get": tool(schema.StatusArgs, "Read observed projectName, playing, tempoBpm, positionBeats, metronome and loop settings. Recording/automation fields are arrangerRecordEnabled, arrangerAutomationWriteEnabled and clipLauncherAutomationWriteEnabled; require each explicitly false before stopped-fixture edits, not missing/null. One response covers project-label and playback-safety preflight; the name is not full-path identity or an atomic lock.", True),
+    "transport.set": tool(schema.TransportSetArgs, "Change only supplied transport fields; e.g. tempoBpm=120 playing=false. Supported tempo range 20..666 BPM is a toolkit bound. Beat positions are nonnegative; loop duration is positive and loop end finite. Playback can produce audio. Recording or automation-write mode blocks changes except an explicit playing=false stop; modes are never silently disabled.", False, {"tempoBpm": 120.0, "playing": False}),
+    "devices.list": tool(schema.DeviceArgs, "Read source-bound top-level device observations without changing host cursor/selection. Discover zero-based deviceIndex and exact expectedDeviceName, within the returned window.", True, {"trackId": TRACK}),
+    "devices.get": tool(schema.ParameterArgs, "Read a source-bound device's state and unsupported-interface details without selecting it. Use exact name and zero-based index from devices.list.", True, TARGET),
+    "devices.layers.list": tool(schema.LayerListArgs, "Discover one layer level beneath an explicit root parent without selection. Fixed zero-offset windows cover at most 2 layers and 2 child devices per layer, not a complete hierarchy. Inspect observed counts, completeness and readiness before using layerId, childDeviceIndex, exact expectedChildDeviceName and discoveryToken. Pads, slots and deeper targets are unsupported.", True, {"parent": LAYER_PARENT}),
+    "devices.set": tool(schema.DeviceSetArgs, "Enable or bypass an explicitly identified device using enabled=true/false. Inspect fresh observation or unknown outcome before another write.", False, {**TARGET, "enabled": False}),
+    "devices.select": tool(schema.ParameterArgs, "Explicitly select this device in the host UI. Unlike source-bound reads, this intentionally changes selection.", False, TARGET),
+    "devices.catalog": tool(schema.StatusArgs, "Discover installed Poly/FX/Note Grid factory device files using the host's installationRoot. Copy kind=file and path into devices.insert with an observed track/count. Only existing files are listed; no guessed community UUIDs or exhaustive plug-in inventory. File presence is not insertion or musical verification.", True),
+    "devices.insert": tool(schema.DeviceInsertArgs, "Append a native device, plug-in or preset to the track's end chain. Discover expectedDeviceCount with devices.list; truncated windows are rejected. kind=bitwig requires canonical UUID id; vst2 signed int32 decimal id; vst3 32 hex id; clap printable ASCII id. kind=file requires absolute normalized path instead of id. No shell/path expansion. An observed added device does not prove its requested native UUID: inspect requestedIdentifierVerified. Insertion can load plug-ins or produce audio; observe before retrying.", False, {"trackId": TRACK, "expectedDeviceCount": 0, "kind": "clap", "id": "org.example.synth"}),
+    "devices.remote.get": tool(schema.ParameterArgs, "Read a source-device-bound remote-control page and fresh contextToken without changing the GUI page. Discover exact page/control names and zero-based indices. Token tracks observed metadata, not unobservable same-name remaps.", True, TARGET),
+    "devices.remote.page": tool(schema.RemotePageArgs, "Change this extension's independent remote page, not the GUI-selected page. Use current contextToken and target pageIndex/expectedPageName from devices.remote.get; get a fresh token after switching.", False, {**TARGET, "contextToken": "from-devices.remote.get", "pageIndex": 0, "expectedPageName": "Main"}),
+    "devices.remote.set": tool(schema.RemoteSetArgs, "Set one normalized remote control with exact page/control names and fresh contextToken from devices.remote.get. Indices are zero-based; inspect fresh same-source value verification. Unobservable same-name mapping changes are not guaranteed detectable.", False, {**TARGET, "contextToken": "from-devices.remote.get", "expectedPageName": "Main", "parameterIndex": 0, "expectedParameterName": "Cutoff", "normalizedValue": 0.5}),
+    "parameters.list": tool(schema.ParameterArgs, "Read source-bound direct parameters and contextToken without changing host cursor/selection. Preserve trackId, deviceIndex, exact expectedDeviceName and fresh token for parameters.set. Bank context is not persistent physical-device identity.", True, TARGET),
+    "parameters.set": tool(schema.SetArgs, "Set one normalized direct parameter using the exact target, parameterId and contextToken from parameters.list. Example: value=0.5. Inspect scope and verification. Never retry an unknown outcome without inspecting state.", False, {**TARGET, "contextToken": "from-parameters.list", "parameterId": "from-parameters.list", "value": 0.5}),
+    "parameters.layer.list": tool(schema.LayerParameterArgs, "Read one discovered layer child's direct parameters and contextToken without selection. Supply the explicit parent and fresh discoveryToken from devices.layers.list. Structural ancestor changes invalidate tokens; names are metadata checks, not persistent identity. Physically rebound child sources fail closed without a genuine provenance boundary. No nested remotes, deeper layers, pads, slots or Grid-private targeting.", True, LAYER_TARGET),
+    "parameters.layer.set": tool(schema.LayerSetArgs, "Set one normalized layer-child direct parameter in 0..1 using the exact discovered target, discoveryToken and fresh contextToken/parameterId from parameters.layer.list. Inspect readiness, scope and observed verification; never retry an unknown outcome without inspecting state. No selection or GUI fallback.", False, {**LAYER_TARGET, "contextToken": "from-parameters.layer.list", "parameterId": "from-parameters.layer.list", "value": 0.5}),
+    "modulators.capabilities": tool(schema.StatusArgs, "Inspect independent primary-modulator discovery and QEE string-panel read bindings under the exact Bitwig version/loaded-JAR hash gate. writeAvailable is false; nativeVerification is not_established_by_binding. Binding availability does not establish reachable instance, DSP or native acceptance.", True),
+    "modulators.list": tool(schema.ModulatorListArgs, "Inspect primary modulators on one explicit root device without selection, loading contents or reading values. Discover parent trackId with tracks.list and deviceIndex/exact expectedDeviceName with devices.list. offset 0..100000, limit 1..128 (default 64). Rows distinguish current modulatorId, typeId, raw names and exact parameterId descriptors; unsupported children remain explicit and unavailable contents are metadata-only. No secondary/nested modulators, mappings or complete-family coverage. Pages are independent observations, not a revision-consistent cursor; parent names are checks, not durable identity.", True,
+        {"parent": {"trackId": TRACK, "deviceIndex": 0, "expectedDeviceName": "Polymer"}, "offset": 0, "limit": 64}),
+    "modulators.parameters.get": tool(schema.ModulatorParameterGetArgs, "Read one exact QEE string panel on a primary modulator of an explicit root device, without selection, mutation or content loading. Use fresh modulatorId and exact addressable parameterId from modulators.list, never names, typeId or index aliases; example UUIDs are placeholders. Reacquire current IDs after reopen or identity changes. Empty parameterId is valid when unique; IDs and raw values are bounded to 1024 UTF-16 units, never truncated. Empty strings, whitespace and Unicode are preserved; kind:string/controlFamily:string_panel with null labels/shortLabel/display. Other families reject unsupported_scope. readContext observes owning-project/context lifecycle, not active-project identity, write authorization or atomic snapshot guarantees.", True,
+        {"parent": {"trackId": TRACK, "deviceIndex": 0, "expectedDeviceName": "Polymer"}, "modulatorId": "abcdef01-2345-6789-abcd-0123456789ab", "parameterId": "LABEL"}),
+    "grid.capabilities": tool(schema.StatusArgs, "Inspect Grid bindings and the exact Bitwig 6.1.3/loaded-JAR hash gate. Reports catalog, structure, typed-parameter inspection, guarded raw parameter writes, module move/delete, moduleInsert, moduleRename and single-input connection bindings separately; unavailable write bindings do not disable reads. Binding availability is not native runtime, DSP or undo verification. Undo commands remain unsupported.", True),
+    "grid.catalog": tool(schema.GridCatalogArgs, "Read native Grid MODULE type UUIDs and names, not devices or module instances. Version/hash gated. query is a case-insensitive name substring (max 128 UTF-16 units); offset 0..100000, limit 1..256 (default 64), deterministic ordering. Inspect window completeness; catalog presence does not prove graph or parameter coverage.", True, {}, {"query": "osc", "offset": 0, "limit": 32}),
+    "grid.get": tool(schema.GridGetArgs, "Read a version/hash-gated Grid graph without selecting or changing the device. For layout, wiring or naming use includeParameters=false; discover parameter IDs with a small parameter-including module page only when needed, then grid.parameters.get before parameter CAS writes. Discover trackId with tracks.list, then deviceIndex and exact expectedDeviceName with devices.list. moduleOffset 0..100000, moduleLimit 1..128 (default 64), includeParameters defaults true. Exact QEE string panels are readable, not writable: strings preserve whitespace/Unicode, with null labels/display. String values over 1024 UTF-16 units reject the parameter-including page; includeParameters=false reads structure only. window.complete covers the module page, not all native children; structure-only reads intentionally report top-level complete=false. Inspect coverage/unsupported; instance UUID, type UUID and list-local key are different identities; no native revision or full snapshot guarantee across pages. This read performs no graph writes or native undo.", True, {**TARGET, "moduleOffset": 0, "moduleLimit": 32, "includeParameters": False}, TARGET),
+    "grid.parameters.get": tool(schema.GridParameterGetArgs, "Read one version/hash-gated Grid module parameter and native edit-context observations without selection or mutation. Use explicit trackId/deviceIndex/expectedDeviceName and a fresh grid.get module instanceId as moduleId (reacquire after project reopen), plus its exact parameterId, never a display name or type UUID. parameterId may be empty and is bounded to 1024 UTF-16 units. Exact QEE string panels report kind:string/controlFamily:string_panel, exact bounded strings and null labels/display, without a linked-consumer prerequisite; they are read-only even when supported/isSettable is true. Unrelated values are not read. editContext reports observations only, not write authorization, readiness, DSP or undo proof. This read performs no mutation or native undo; no automatic retries or GUI fallback.", True, {**TARGET, "moduleId": "abcdef01-2345-6789-abcd-0123456789ab", "parameterId": "from-grid.get"}),
+    "grid.parameters.set": tool(schema.GridParameterSetArgs, "Set one version/hash-gated Grid module parameter in its native RAW domain, not normalized or formatter/display units. Use an explicit current device target, fresh grid.get module instanceId as moduleId and exact parameterId; examples contain placeholder IDs, not live targets. For supported scalars or boolean panels, read grid.parameters.get immediately before writing and supply its typed kind/value as expectedKind/expectedValue. String panels are read-only and rejected, including apparent no-ops; string write kinds/values are invalid input. Exact stale-state checks precede even an already-matching no-op. Boolean requires JSON bool; integer/enum signed int32 JSON integer tokens; float finite JSON numbers. Enum values are actual listed option values, never ordinals. Native range, representability, observed stopped/nonrecording/nonautomation state and current native context are guarded; nothing is clamped or coerced. Already-matched values skip native dispatch. Result distinguishes model readback from no-op; neither proves DSP acknowledgement or one-call-one-Undo. The dispatched native operation is undo-aware, not an undo-command or grouping API. After timeout/error with unknown outcome, inspect grid.parameters.get and actual host state before another write: no retry, rollback or GUI fallback.", False,
+        {**TARGET, "moduleId": "abcdef01-2345-6789-abcd-0123456789ab", "parameterId": "from-grid.get", "expectedKind": "float", "expectedValue": 0.25, "value": 0.5},
+        {**TARGET, "moduleId": "abcdef01-2345-6789-abcd-0123456789ab", "parameterId": "from-grid.get", "expectedKind": "boolean", "expectedValue": False, "value": True}),
+    "grid.modules.insert": tool(schema.GridModuleInsertArgs, "Insert one known native MODULE type into an existing Grid device using explicit trackId/deviceIndex/exact expectedDeviceName. Discover typeId through grid.catalog: supply its canonical type UUID, not a module instance ID, name or arbitrary file path. Example IDs are placeholders, not live targets. x/y require signed int32 JSON integer tokens and specify an absolute native anchor, not pixels or deltas. Native layout may reflow existing modules; inspect the bounded actual graph, new moduleId/typeId, requestedPosition/actualPosition and matchesRequested. Module instance IDs change on project reopen: reacquire them through grid.get. This asynchronous operation reports loaderDispatched and placementDispatched separately; loading is not placement or success. Observed stopped/nonrecording/nonautomation state, native context and complete bounded geometry are required; at most 128 modules including the new module are supported. Timeout is not cancellation: native loading may outlive the request and block further topology writes. Never blindly retry an unknown outcome; inspect actual state. Availability is gated independently by moduleInsert; no GUI fallback, DSP or undo guarantee.", False,
+        {**TARGET, "typeId": "abcdef01-2345-6789-abcd-0123456789ab", "x": 4, "y": 2}),
+    "grid.modules.rename": tool(schema.GridModuleRenameArgs, "Rename one current Grid module instance UUID from fresh grid.get, using explicit trackId/deviceIndex/exact expectedDeviceName. Reacquire moduleId after reopen; examples are placeholders. expectedCustomName is the exact raw customName, never effective name or typeName, and must match before even a no-op. Both names are required JSON strings, empty allowed, at most 1024 UTF-16 units; Unicode and whitespace are preserved without coercion, trimming or truncation. customName='' resets the override through native semantics. Requires a complete bounded graph of at most 128 modules and observed stopped/nonrecording/nonautomation context. One native name setter is used only when changed, followed by later document observation and the bounded actual graph without parameters. Inspect previous/actual raw and effective names and verification. Native property bookkeeping is not proof of one Undo grouping, DSP acknowledgement, persistence or rollback. Context changes, cancellation or failure after dispatch yield unknown; inspect state rather than blindly retry. No selection or GUI fallback.", False,
+        {**TARGET, "moduleId": "abcdef01-2345-6789-abcd-0123456789ab", "expectedCustomName": "", "customName": "Lead = α"},
+        {**TARGET, "moduleId": "abcdef01-2345-6789-abcd-0123456789ab", "expectedCustomName": "Lead = α", "customName": ""}),
+    "grid.modules.move": tool(schema.GridModuleMoveArgs, "Move one current Grid module instance UUID from fresh grid.get, using explicit trackId/deviceIndex/exact expectedDeviceName. Reacquire moduleId after reopen; examples are placeholders, not live targets. expectedX/expectedY must exactly match its current native anchor before even a no-op. x/y are absolute native anchor coordinates, not deltas or pixels; all four coordinates require signed int32 JSON integer tokens. Native full-graph geometry/bounds and observed stopped/nonrecording/nonautomation context are checked before dispatch; only complete supported layouts of at most 128 modules and occupied y-span 65536 are supported. Native collision rejection and full-graph reflow may change other modules and produce an actual position different from the request. Inspect previous/requested/actual position, matchesRequested and bounded post-event graph observations: these are not DSP acknowledgement, atomicity or complete undo-group proof. No copy, GUI selection fallback, automatic retry or rollback; inspect actual state after an unknown outcome.", False,
+        {**TARGET, "moduleId": "abcdef01-2345-6789-abcd-0123456789ab", "expectedX": 0, "expectedY": 0, "x": 4, "y": 2}),
+    "grid.modules.delete": tool(schema.GridModuleArgs, "Selectively delete one current Grid module instance UUID from fresh grid.get, using explicit trackId/deviceIndex/exact expectedDeviceName. Reacquire moduleId after reopen; examples are placeholders, not live targets. This is not clear-all, GUI-selected deletion or missing-is-success. Retains native bypass/reconnection semantics, potentially changing the full graph. Native full-graph geometry/bounds and observed stopped/nonrecording/nonautomation context are checked before dispatch; only complete supported layouts of at most 128 modules and occupied y-span 65536 are supported. Inspect removal and bounded surviving-layout/connection observations after a later document event, not DSP acknowledgement, atomicity or complete undo-group proof. No automatic retry, rollback or GUI fallback; inspect actual state after an unknown outcome.", False,
+        {**TARGET, "moduleId": "abcdef01-2345-6789-abcd-0123456789ab"}),
+    "grid.connections.set": tool(schema.GridConnectionSetArgs, "Set one input's source in a version/hash-gated current Grid graph. Use explicit trackId/deviceIndex/exact expectedDeviceName and fresh grid.get module instance UUIDs and direction-specific port keys, not names, indices or type UUIDs. Both expectedSource and source are required: each is JSON null or exactly {moduleId,portKey}. expectedSource must match the current source before even an already-matching no-op; source=null disconnects. Keys may be empty and are bounded to 1024 UTF-16 units. Examples are placeholders, not live targets. Only a complete bounded graph of at most 128 modules and supported native input implementations are eligible; observed stopped/nonrecording/nonautomation and native edit-context safety are checked. Native repair may reject the requested link or alter other links: inspect actualSource, matchesRequested and the full bounded graph after the later document event. No automatic reconnect, rollback, retry or GUI fallback. Observations are not atomicity, DSP, undo/redo, engine or persistence proof; unknown topology outcomes quarantine further topology edits for this extension instance.", False,
+        {**TARGET, "targetModuleId": "abcdef01-2345-6789-abcd-0123456789ab", "targetPortKey": "from-grid.get-input", "expectedSource": None, "source": {"moduleId": "abcdef02-2345-6789-abcd-0123456789ab", "portKey": "from-grid.get-output"}},
+        {**TARGET, "targetModuleId": "abcdef01-2345-6789-abcd-0123456789ab", "targetPortKey": "from-grid.get-input", "expectedSource": {"moduleId": "abcdef02-2345-6789-abcd-0123456789ab", "portKey": "from-grid.get-output"}, "source": None}),
+    "launcher.list": tool(schema.DeviceArgs, "Discover occupied and empty launcher clip slots for one track UUID; slotIndex is zero-based within the bounded window.", True, {"trackId": TRACK}),
+    "launcher.create": tool(schema.ClipCreateArgs, "Create a named MIDI clip only in an empty zero-based slot. Selects that clip in the host UI to bind and verify the explicit target. Example: trackId=<UUID> slotIndex=0 lengthBeats=4 name=Sketch. Then use notes.edit with an explicit grid/window; never overwrites an existing clip.", False, {**CLIP, "lengthBeats": 4, "name": "Sketch"}),
+    "launcher.import": tool(schema.ClipImportArgs, "Import a local audio or clip file into an EMPTY explicit launcher slot by track UUID and zero-based slotIndex (0..15). Occupied slots reject; no overwrite option. path must be absolute and normalized, without URI, shell/path expansion or control characters. The host checks file existence/readability; the client checks syntax only. Result reports only observed slot content transition, not file identity or decoded audio verification. Never blindly retry an unknown outcome.", False, {**CLIP, "path": "/absolute/path/audio.wav"}),
+    "launcher.launch": tool(schema.ClipArgs, "Launch an existing clip by explicit track UUID and zero-based slot. Can start playback and produce audio. Recording and both automation-write flags must be observed false; modes are never silently disabled. Dispatch does not prove musical/audio completion.", False, CLIP),
+    "launcher.stop": tool(schema.DeviceArgs, "Stop launcher playback on one track UUID; does not delete clips or stop the entire transport.", False, {"trackId": TRACK}),
+    "notes.read": tool(schema.NoteWindowArgs, "Read an explicit clip/channel/grid/pitch window; selects the target clip in the host UI. channel is zero-based MIDI 0..15; pitch is MIDI 0..127; beat 0 is clip start. stepSizeBeats=0.25,startStep=0,steps=16 covers four beats. Inspect gridReadinessLimitation: scheduled settling is not a host-data barrier; late callbacks lack window identity. Inspect continuingAtWindowStart, notesInWindow, notesReturned and completeWindow: at most 2048 onsets returned; subdivide steps or pitchCount when incomplete. completeClip is always false; onsetPrecision is grid_cell, not arbitrary sub-grid/multiple-onset fidelity.", False, NOTE_WINDOW),
+    "notes.edit": tool(schema.NoteEditArgs, "Edit up to 256 onset cells; selects the target clip in the host UI. Each set requires op=set, absolute beat, MIDI pitch, velocity 1..127 and durationBeats; clear requires only op=clear,beat,pitch. Beat/duration must align exactly to stepSizeBeats without rounding; entire note must fit requested window and observed clip loop. No duplicate cells, overlapping same-pitch sets or clear-all; sustains are protected and already-matching cells are not rewritten. Example edits=[{\"op\":\"set\",\"beat\":0,\"pitch\":60,\"velocity\":90,\"durationBeats\":1}]. Inspect gridReadinessLimitation: scheduled settling is not a host-data barrier, and late callbacks lack window identity. Per-edit readbacks are separate from the capped 2048-onset listing. Inspect per-edit verification and completeWindow, then notes.read. No automatic retry.", False, {**NOTE_WINDOW, "edits": [{"op": "set", "beat": 0.0, "pitch": 60, "velocity": 90, "durationBeats": 1.0}]}),
+    "actions.list": tool(schema.StatusArgs, "List native host Action IDs, names and categories. Availability does not prove completion in the current UI context.", True),
+    "actions.invoke": tool(schema.ActionArgs, "Invoke one exact ID from actions.list in the current host/UI context. May edit the project or open a dialog. Returns dispatched only, never completion; inspect state before another write and do not blindly retry.", False, {"actionId": "from-actions.list"}),
+}
+
+
+def validate_call(method: str, arguments: dict[str, Any]) -> tuple[dict[str, Any], int]:
+    if method not in TOOLS:
+        raise ValueError(f"Unknown method: {method}. Use list or describe <method> offline.")
+    args = TOOLS[method].model.model_validate(arguments)
+    return args.model_dump(exclude={"timeoutMs"}, exclude_unset=True), args.timeoutMs

bitwig_agent/cli.py

@@ -0,0 +1,118 @@
+"""Offline discovery and explicit one-shot calls; never starts/configures Bitwig."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import sys
+from typing import Any
+
+from bitwig_agent.catalog import TOOLS, validate_call
+from bitwig_agent.client import BridgeClient, BridgeError, configured_port, load_json
+
+
+class ArgumentParser(argparse.ArgumentParser):
+    def error(self, message: str) -> None:
+        raise ValueError(message)
+
+
+def parser() -> ArgumentParser:
+    result = ArgumentParser(add_help=False, allow_abbrev=False)
+    result.add_argument("command", nargs="?", default="help")
+    result.add_argument("arguments", nargs="*")
+    result.add_argument("--params", help="Strict JSON object; cannot be mixed with key=value arguments")
+    result.add_argument("--timeout-ms", type=int)
+    result.add_argument("--help", "-h", action="store_true")
+    return result
+
+
+def help_payload() -> dict[str, Any]:
+    return {
+        "usage": ["bitwig-agent-rpc list [domain]", "bitwig-agent-rpc describe <method>",
+                  "bitwig-agent-rpc help [method]", "bitwig-agent-rpc <method> key=value ... [--timeout-ms 5000]",
+                  "bitwig-agent-rpc <method> --params '{\"key\":\"value\"}'"],
+        "discovery": "list, help and describe are offline. capabilities queries the running host.",
+        "arguments": "Strings are unquoted values (shell-quote spaces); numbers/booleans/arrays/objects use strict JSON. Booleans are true/false. Explicit null is accepted only where the method schema allows it; required nullable fields must still be supplied. Duplicate/extra fields are rejected. Raw --params is equally strict.",
+        "targets": "Discover track UUIDs with tracks.list and exact device names/zero-based indices with devices.list. Clip slots and MIDI channels are zero-based. Example UUIDs are placeholders.",
+        "safety": "One request, no retries. A timeout is not cancellation; inspect actual host state before another write after an unknown outcome. Output preserves host results/errors without upgrading dispatched to observed.",
+        "exitCodes": {"0": "success or offline discovery", "1": "host/transport error", "2": "invalid arguments/configuration; not dispatched"},
+        "methods": list(TOOLS),
+    }
+
+
+def parse_arguments(method: str, pairs: list[str], raw: str | None, timeout_ms: int | None) -> tuple[dict[str, Any], int]:
+    if method not in TOOLS:
+        raise ValueError(f"Unknown method: {method}. Use list or describe <method> offline.")
+    if raw is not None:
+        if pairs:
+            raise ValueError("--params cannot be mixed with key=value arguments")
+        values = load_json(raw)
+        if not isinstance(values, dict):
+            raise ValueError("--params must be a JSON object")
+    else:
+        properties = TOOLS[method].model.model_json_schema()["properties"]
+        values = {}
+        for pair in pairs:
+            key, separator, value = pair.partition("=")
+            if not separator or not key:
+                raise ValueError(f"Expected key=value, got {pair!r}")
+            if key in values:
+                raise ValueError(f"Duplicate argument: {key}")
+            if key not in properties:
+                raise ValueError(f"Unknown argument for {method}: {key}")
+            if properties[key].get("type") == "string":
+                values[key] = load_json(value) if value.startswith('"') else value
+            else:
+                values[key] = load_json(value)
+    if timeout_ms is not None:
+        if "timeoutMs" in values:
+            raise ValueError("Specify timeout once: timeoutMs or --timeout-ms")
+        values["timeoutMs"] = timeout_ms
+    return validate_call(method, values)
+
+
+async def execute(argv: list[str]) -> tuple[dict[str, Any], int]:
+    """Return the exact JSON envelope and exit code; no output side effects."""
+    try:
+        args = parser().parse_intermixed_args(argv)
+        command = args.command
+        arguments = args.arguments
+        if args.help:
+            arguments = [] if command == "help" else [command]
+            command = "help"
+        if command in {"help", "list", "describe"}:
+            if args.params is not None or args.timeout_ms is not None:
+                raise ValueError("Offline discovery does not accept --params or --timeout-ms")
+            if command == "list":
+                if len(arguments) > 1:
+                    raise ValueError("Usage: list [domain]")
+                prefix = arguments[0] + "." if arguments else ""
+                entries = {name: {"description": spec.description, "readOnly": spec.read_only}
+                           for name, spec in TOOLS.items() if not prefix or name.startswith(prefix)}
+                if not entries:
+                    raise ValueError(f"Unknown domain: {arguments[0]}")
+                return {"result": {"methods": entries}}, 0
+            if command == "help" and not arguments:
+                return {"result": help_payload()}, 0
+            if len(arguments) != 1 or arguments[0] not in TOOLS:
+                raise ValueError("Usage: describe <known-method> (use list to discover methods)")
+            name = arguments[0]
+            return {"result": {"method": name, **TOOLS[name].describe()}}, 0
+        params, timeout_ms = parse_arguments(command, arguments, args.params, args.timeout_ms)
+        result = await BridgeClient(configured_port()).call(command, params, timeout_ms)
+        return {"result": result}, 0
+    except BridgeError as exc:
+        return {"error": exc.error}, 1
+    except (ValueError, TypeError, RecursionError) as exc:
+        return {"error": {"code": "invalid_params", "message": str(exc), "outcome": "not_dispatched"}}, 2
+
+
+def main(argv: list[str] | None = None) -> int:
+    payload, exit_code = asyncio.run(execute(sys.argv[1:] if argv is None else argv))
+    print(json.dumps(payload, ensure_ascii=False, allow_nan=False, separators=(",", ":")))
+    return exit_code
+
+
+if __name__ == "__main__":
+    sys.exit(main())

bitwig_agent/client.py

@@ -0,0 +1,118 @@
+"""One newline-delimited JSON request per loopback connection, without retries."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import math
+import os
+import uuid
+from typing import Any
+from bitwig_agent.catalog import TOOLS, validate_call
+
+MAX_BYTES = 1024 * 1024
+METHODS = frozenset(TOOLS)
+
+
+class BridgeError(Exception):
+    """Keep host error fields, including an unknown outcome, intact."""
+
+    def __init__(self, error: dict[str, Any]):
+        self.error = error
+        super().__init__(error["message"])
+
+
+def _reject_constant(value: str) -> None:
+    raise ValueError(f"Non-finite JSON number: {value}")
+
+
+def _finite_float(value: str) -> float:
+    parsed = float(value)
+    if not math.isfinite(parsed):
+        raise ValueError("JSON number is outside the finite float range")
+    return parsed
+
+
+def _unique_object(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+    result = {}
+    for key, value in pairs:
+        if key in result:
+            raise ValueError(f"Duplicate JSON field: {key}")
+        result[key] = value
+    return result
+
+
+def load_json(value: str) -> Any:
+    """Decode strict JSON, rejecting duplicate keys and non-finite numbers."""
+    return json.loads(value, parse_constant=_reject_constant, parse_float=_finite_float, object_pairs_hook=_unique_object)
+
+
+def configured_port() -> int:
+    value = int(os.environ.get("BITWIG_AGENT_PORT", "61172"))
+    if not 1 <= value <= 65535:
+        raise ValueError("BITWIG_AGENT_PORT must be in 1..65535")
+    return value
+
+
+class BridgeClient:
+    def __init__(self, port: int = 61172, *, response_grace_seconds: float = 1.0):
+        if type(port) is not int or not 1 <= port <= 65535:
+            raise ValueError("port must be in 1..65535")
+        self.port = port
+        self.response_grace_seconds = response_grace_seconds
+
+    async def call(self, method: str, params: dict[str, Any], timeout_ms: int = 5000) -> dict[str, Any]:
+        if method not in METHODS or not isinstance(params, dict):
+            raise ValueError("A known method and object params are required")
+        if type(timeout_ms) is not int or not 100 <= timeout_ms <= 10000:
+            raise ValueError("timeoutMs must be an integer in 100..10000")
+        if "timeoutMs" in params:
+            raise ValueError("Pass timeout_ms separately from host params")
+        params, _ = validate_call(method, {**params, "timeoutMs": timeout_ms})
+        request_id = uuid.uuid4().hex
+        request = {"id": request_id, "method": method, "params": params, "timeoutMs": timeout_ms}
+        payload = (json.dumps(request, allow_nan=False, separators=(",", ":")) + "\n").encode("utf-8")
+        if len(payload) > MAX_BYTES:
+            raise ValueError("Request exceeds 1 MiB")
+
+        writer = None
+        dispatched = False
+        try:
+            # The host deadline bounds mutations. The extra second only lets its
+            # final response reach us; it never extends or replays the request.
+            async with asyncio.timeout(timeout_ms / 1000 + self.response_grace_seconds):
+                reader, writer = await asyncio.open_connection("127.0.0.1", self.port, limit=MAX_BYTES)
+                dispatched = True
+                writer.write(payload)
+                await writer.drain()
+                raw = await reader.readuntil(b"\n")
+                if len(raw) > MAX_BYTES:
+                    raise ValueError("Response exceeds 1 MiB")
+                response = load_json(raw.decode("utf-8"))
+                if not isinstance(response, dict) or response.get("id") != request_id:
+                    raise ValueError("Response id does not match request")
+                if ("result" in response) == ("error" in response):
+                    raise ValueError("Response must contain exactly one of result or error")
+                if "error" in response:
+                    error = response["error"]
+                    if not isinstance(error, dict) or not isinstance(error.get("code"), str) or not isinstance(error.get("message"), str) or error.get("outcome") not in ("not_dispatched", "not_applied", "unknown"):
+                        raise ValueError("Malformed host error")
+                    raise BridgeError(error)
+                if not isinstance(response["result"], dict):
+                    raise ValueError("Host result must be an object")
+                return response["result"]
+        except BridgeError:
+            raise
+        except (TimeoutError, OSError, ValueError, RecursionError, asyncio.IncompleteReadError, asyncio.LimitOverrunError) as exc:
+            outcome = "unknown" if dispatched else "not_dispatched"
+            code = "deadline_exceeded" if isinstance(exc, TimeoutError) else "transport_error"
+            raise BridgeError({"code": code, "message": f"{type(exc).__name__}: {exc}. Inspect host state before another write; request was not retried.", "outcome": outcome}) from exc
+        finally:
+            if writer is not None:
+                writer.close()
+                try:
+                    await asyncio.wait_for(writer.wait_closed(), timeout=0.2)
+                except (OSError, TimeoutError):
+                    pass
+
+

bitwig_agent/install.py

@@ -0,0 +1,130 @@
+"""Install the matching release extension, or an explicitly supplied local build."""
+import argparse
+import hashlib
+from http.client import HTTPException
+from importlib.metadata import version
+import json
+import os
+from pathlib import Path
+import re
+import sys
+import tempfile
+import time
+from urllib.error import URLError
+from urllib.request import urlopen
+
+
+_EXTENSION = "BitwigAgent.bwextension"
+_RELEASES = "https://github.com/BANANASJIM/bitwig-agent/releases/download"
+_MAX_EXTENSION_BYTES = 32 * 1024 * 1024
+_MAX_CHECKSUM_BYTES = 64 * 1024
+
+
+def _default_destination() -> Path:
+    base = Path.home()
+    if sys.platform in ("darwin", "win32"):
+        base /= "Documents"
+    return base / "Bitwig Studio" / "Extensions"
+
+
+def _download(url: str, limit: int) -> bytes:
+    deadline = time.monotonic() + 60
+    with urlopen(url, timeout=30) as response:
+        chunks = []
+        size = 0
+        while True:
+            if time.monotonic() >= deadline:
+                raise ValueError(f"Download timed out: {url}")
+            chunk = response.read1(min(64 * 1024, limit + 1 - size))
+            if not chunk:
+                break
+            chunks.append(chunk)
+            size += len(chunk)
+            if size > limit:
+                raise ValueError(f"Download exceeds {limit} bytes: {url}")
+        length = response.headers.get("Content-Length")
+        if length is not None and size != int(length):
+            raise ValueError(f"Incomplete download: {url}")
+    return b"".join(chunks)
+
+
+def _release_extension(package_version: str) -> bytes:
+    base = f"{_RELEASES}/v{package_version}"
+    manifest = _download(f"{base}/SHA256SUMS", _MAX_CHECKSUM_BYTES).decode("utf-8")
+    checksums = []
+    for line in manifest.splitlines():
+        if not line.strip():
+            continue
+        match = re.fullmatch(r"([0-9a-fA-F]{64}) [ *]([^\r\n]+)", line)
+        if match is None:
+            raise ValueError("Malformed SHA256SUMS entry")
+        digest, filename = match.groups()
+        if filename == _EXTENSION:
+            checksums.append(digest.lower())
+    if len(checksums) != 1:
+        raise ValueError(f"SHA256SUMS must contain exactly one entry for {_EXTENSION}")
+    data = _download(f"{base}/{_EXTENSION}", _MAX_EXTENSION_BYTES)
+    if hashlib.sha256(data).hexdigest() != checksums[0]:
+        raise ValueError(f"SHA256 mismatch for {_EXTENSION}; installation unchanged")
+    return data
+
+
+def _atomic_write(target: Path, data: bytes) -> None:
+    staging = None
+    try:
+        with tempfile.NamedTemporaryFile(prefix=f".{target.name}.", suffix=".tmp", dir=target.parent, delete=False) as stream:
+            staging = Path(stream.name)
+            stream.write(data)
+            stream.flush()
+            os.fsync(stream.fileno())
+        staging.replace(target)
+    finally:
+        if staging is not None:
+            staging.unlink(missing_ok=True)
+
+
+def _install(data: bytes, destination: Path) -> None:
+    target = destination / _EXTENSION
+    if target.exists():
+        old = target.read_bytes()
+        if old == data:
+            print(f"Already installed: {target}")
+            return
+        # Bitwig scans recursively: backups must live outside Extensions.
+        backup = destination.parent / ".bitwig-agent-backups" / hashlib.sha256(old).hexdigest() / _EXTENSION
+        if backup.exists():
+            if backup.read_bytes() != old:
+                raise ValueError(f"Existing backup has unexpected contents: {backup}")
+        else:
+            backup.parent.mkdir(parents=True, exist_ok=True)
+            _atomic_write(backup, old)
+        print(f"Previous build preserved: {backup}")
+    destination.mkdir(parents=True, exist_ok=True)
+    _atomic_write(target, data)
+    print(f"Installed: {target}")
+    print("Enable Bitwig Agent under Bitwig Settings > Controllers; no MIDI ports are required.")
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--version", action="version", version=f"%(prog)s {version('bitwig-agent')}")
+    parser.add_argument("--extension", type=Path, help="Install this local extension instead of downloading a release")
+    parser.add_argument("--destination", type=Path, default=_default_destination(), help="Bitwig Extensions directory")
+    parser.add_argument("--mcp-config", action="store_true", help="Print MCP configuration only; do not download or install")
+    args = parser.parse_args(argv)
+    if args.mcp_config:
+        print(json.dumps({"mcpServers": {"bitwig-agent": {
+            "command": sys.executable,
+            "args": ["-m", "bitwig_agent"],
+            "env": {"BITWIG_AGENT_PORT": "61172"},
+        }}}, indent=2))
+        return
+    try:
+        data = args.extension.read_bytes() if args.extension is not None else _release_extension(version("bitwig-agent"))
+        _install(data, args.destination)
+    except (OSError, ValueError, URLError, HTTPException) as exc:
+        parser.exit(1, f"{parser.prog}: error: {exc}\n")
+
+
+if __name__ == "__main__":
+    main()

bitwig_agent/schema.py

@@ -0,0 +1,372 @@
+"""Strict public arguments shared by MCP, the diagnostic CLI and TCP callers."""
+
+from __future__ import annotations
+
+from decimal import Decimal
+import math
+import re
+from pathlib import PurePosixPath
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+Nonempty = Annotated[str, Field(min_length=1, max_length=4096)]
+TrackId = Annotated[str, Field(pattern=r"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$")]
+UnitValue = Annotated[float, Field(ge=0, le=1)]
+
+
+def omitted():
+    """Absent is allowed; explicit null is not part of the wire contract."""
+    return Field(default=None, json_schema_extra=lambda schema: schema.pop("default", None))
+
+
+def validate_local_path(value: str) -> None:
+    path = PurePosixPath(value)
+    if not path.is_absolute() or value.startswith("//") or str(path) != value or ".." in path.parts or any(ord(c) < 32 or 127 <= ord(c) <= 159 for c in value):
+        raise ValueError("path must be an absolute normalized path without control characters")
+
+
+class StrictModel(BaseModel):
+    model_config = ConfigDict(strict=True, extra="forbid", allow_inf_nan=False)
+
+    @model_validator(mode="after")
+    def validate_host_string_lengths(self):
+        # Java String.length counts UTF-16 units, unlike JSON Schema maxLength.
+        for key, field in type(self).model_fields.items():
+            value = getattr(self, key)
+            if isinstance(value, str):
+                length = len(value.encode("utf-16-le", errors="surrogatepass")) // 2
+                for constraint in field.metadata:
+                    limit = getattr(constraint, "max_length", None)
+                    if limit is not None and length > limit:
+                        raise ValueError(f"{key} exceeds {limit} UTF-16 code units")
+        return self
+
+
+class StatusArgs(StrictModel):
+    timeoutMs: int = Field(default=5000, ge=100, le=10000)
+
+
+class DeviceArgs(StatusArgs):
+    trackId: TrackId
+
+
+class ActionArgs(StatusArgs):
+    actionId: Nonempty
+
+
+class ParameterArgs(DeviceArgs):
+    deviceIndex: int = Field(ge=0, le=15)
+    expectedDeviceName: Nonempty
+
+
+class DeviceParent(StrictModel):
+    trackId: TrackId
+    deviceIndex: int = Field(ge=0, le=15)
+    expectedDeviceName: Nonempty
+
+
+class LayerListArgs(StatusArgs):
+    parent: DeviceParent
+
+
+class LayerParameterArgs(LayerListArgs):
+    layerId: TrackId
+    childDeviceIndex: int = Field(ge=0, le=1)
+    expectedChildDeviceName: Nonempty
+    discoveryToken: Nonempty
+
+
+class LayerSetArgs(LayerParameterArgs):
+    contextToken: Nonempty
+    parameterId: Nonempty
+    value: UnitValue
+
+
+class ModulatorListArgs(StatusArgs):
+    parent: DeviceParent
+    offset: int = Field(default=0, ge=0, le=100000)
+    limit: int = Field(default=64, ge=1, le=128)
+
+
+class ModulatorParameterGetArgs(StatusArgs):
+    parent: DeviceParent
+    modulatorId: TrackId = Field(description="Current modulator UUID from modulators.list, not its typeId, name or index; reacquire after reopening or identity changes.")
+    parameterId: str = Field(max_length=1024, description="Exact addressable parameterId from modulators.list, not a display name; empty is valid when unique, at most 1024 UTF-16 code units.")
+
+
+class GridCatalogArgs(StatusArgs):
+    query: str = Field(default="", max_length=128)
+    offset: int = Field(default=0, ge=0, le=100000)
+    limit: int = Field(default=64, ge=1, le=256)
+
+
+class GridGetArgs(ParameterArgs):
+    moduleOffset: int = Field(default=0, ge=0, le=100000)
+    moduleLimit: int = Field(default=64, ge=1, le=128)
+    includeParameters: bool = True
+
+
+class GridModuleInsertArgs(ParameterArgs):
+    typeId: TrackId = Field(description="Canonical MODULE type UUID discovered through grid.catalog, not a module instanceId or file path; the host verifies catalog membership.")
+    x: int = Field(ge=-(2**31), le=2**31 - 1, description="Requested absolute native anchor X, not a relative delta or pixels. Signed int32 JSON integer token; native layout bounds checked by host.")
+    y: int = Field(ge=-(2**31), le=2**31 - 1, description="Requested absolute native anchor Y, not a relative delta or pixels. Signed int32 JSON integer token; native layout bounds checked by host.")
+
+
+class GridModuleArgs(ParameterArgs):
+    moduleId: TrackId = Field(description="Current module instanceId from grid.get; reacquire after reopening the project.")
+
+
+class GridConnectionSource(StrictModel):
+    moduleId: TrackId = Field(description="Current source module instanceId from grid.get, not a type UUID.")
+    portKey: str = Field(max_length=1024, description="Exact output port key from grid.get; empty is valid, at most 1024 UTF-16 code units.")
+
+
+class GridConnectionSetArgs(ParameterArgs):
+    targetModuleId: TrackId = Field(description="Current destination module instanceId from grid.get; reacquire after reopening the project.")
+    targetPortKey: str = Field(max_length=1024, description="Exact input port key from grid.get; empty is valid, at most 1024 UTF-16 code units.")
+    expectedSource: GridConnectionSource | None = Field(description="Required exact prior source from fresh grid.get, or explicit null for an unconnected input. Checked before even an already-matching no-op; never defaults to null.")
+    source: GridConnectionSource | None = Field(description="Required requested output endpoint, or explicit null to disconnect. Must belong to the same current graph; native repair can change the observed result.")
+
+
+class GridModuleRenameArgs(GridModuleArgs):
+    expectedCustomName: str = Field(max_length=1024, description="Exact raw customName from a fresh grid.get, not effective name or typeName. Required even for no-op; empty is valid. At most 1024 UTF-16 code units; no trimming or coercion.")
+    customName: str = Field(max_length=1024, description="Requested raw custom name; empty resets the override through native semantics. Unicode and whitespace are preserved, at most 1024 UTF-16 code units.")
+
+
+class GridModuleMoveArgs(GridModuleArgs):
+    expectedX: int = Field(ge=-(2**31), le=2**31 - 1, description="Fresh native anchor X; exact stale-state check precedes even a no-op. Signed int32 JSON integer token.")
+    expectedY: int = Field(ge=-(2**31), le=2**31 - 1, description="Fresh native anchor Y; exact stale-state check precedes even a no-op. Signed int32 JSON integer token.")
+    x: int = Field(ge=-(2**31), le=2**31 - 1, description="Requested absolute native anchor X, not a relative delta or pixels. Signed int32 JSON integer token; native layout bounds checked by host.")
+    y: int = Field(ge=-(2**31), le=2**31 - 1, description="Requested absolute native anchor Y, not a relative delta or pixels. Signed int32 JSON integer token; native layout bounds checked by host.")
+
+
+class GridParameterGetArgs(GridModuleArgs):
+    parameterId: str = Field(max_length=1024, description="Exact native parameter ID from grid.get, not a name; empty is valid, at most 1024 UTF-16 code units.")
+
+
+class GridParameterSetArgs(GridParameterGetArgs):
+    model_config = ConfigDict(json_schema_extra={
+        "oneOf": [
+            {"properties": {
+                "expectedKind": {"enum": kinds},
+                "expectedValue": value_schema,
+                "value": value_schema,
+            }}
+            for kinds, value_schema in (
+                (["boolean"], {"type": "boolean"}),
+                (["integer", "enum"], {"type": "integer", "minimum": -(2**31), "maximum": 2**31 - 1}),
+                (["float"], {"type": "number"}),
+            )
+        ],
+    })
+
+    expectedKind: Literal["float", "integer", "enum", "boolean"] = Field(
+        description="Fresh typed kind from grid.parameters.get; checked before any already-matching no-op.")
+    expectedValue: bool | int | float = Field(
+        description="Exact current native raw value from a fresh grid.parameters.get, not normalized or display units. Must match expectedKind; no tolerance or coercion.")
+    value: bool | int | float = Field(
+        description="Requested native raw value: boolean JSON bool; integer/enum signed int32 JSON integer token; float finite JSON number. Enum uses an actual listed option value, never an ordinal. Native range/representability are checked before dispatch.")
+
+    @field_validator("expectedValue", "value", mode="before")
+    @classmethod
+    def validate_raw_number(cls, value):
+        if type(value) not in (bool, int, float):
+            raise ValueError("raw value must be a JSON boolean or number, never null or a string")
+        if type(value) is not bool:
+            try:
+                finite = math.isfinite(value)
+            except OverflowError:
+                finite = False
+            if not finite:
+                raise ValueError("raw numeric value must be finite and representable as a native double")
+        return value
+
+    @model_validator(mode="after")
+    def validate_raw_kind(self):
+        for field in ("expectedValue", "value"):
+            value = getattr(self, field)
+            if self.expectedKind == "boolean":
+                if type(value) is not bool:
+                    raise ValueError(f"{field} must be a JSON boolean for boolean kind")
+            elif self.expectedKind in ("integer", "enum"):
+                if type(value) is not int or not -(2**31) <= value < 2**31:
+                    raise ValueError(f"{field} must be a signed int32 JSON integer for {self.expectedKind} kind")
+            elif type(value) not in (int, float):
+                raise ValueError(f"{field} must be a finite JSON number for float kind")
+        return self
+
+
+class SetArgs(ParameterArgs):
+    contextToken: Nonempty
+    parameterId: Nonempty
+    value: UnitValue
+
+
+class DeviceSetArgs(ParameterArgs):
+    enabled: bool
+
+
+class DeviceInsertArgs(DeviceArgs):
+    expectedDeviceCount: int = Field(ge=0, le=15)
+    kind: Literal["bitwig", "vst2", "vst3", "clap", "file"]
+    id: Nonempty = omitted()
+    path: Nonempty = omitted()
+
+    @model_validator(mode="after")
+    def validate_identifier(self):
+        if self.kind == "file":
+            if "id" in self.model_fields_set or "path" not in self.model_fields_set:
+                raise ValueError("file insertion requires path and forbids id")
+            validate_local_path(self.path)
+        else:
+            if "path" in self.model_fields_set or "id" not in self.model_fields_set:
+                raise ValueError("plug-in insertion requires id and forbids path")
+            if self.kind == "bitwig" and not re.fullmatch(r"[0-9a-fA-F]{8}(?:-[0-9a-fA-F]{4}){3}-[0-9a-fA-F]{12}", self.id):
+                raise ValueError("bitwig id must be a canonical UUID")
+            if self.kind == "vst2" and (not re.fullmatch(r"-?(0|[1-9][0-9]{0,9})", self.id) or not -(2**31) <= int(self.id) < 2**31):
+                raise ValueError("vst2 id must be a signed int32 decimal string")
+            if self.kind == "vst3" and not re.fullmatch(r"[0-9a-fA-F]{32}", self.id):
+                raise ValueError("vst3 id must be 32 hexadecimal characters")
+            if self.kind == "clap" and not re.fullmatch(r"[!-~]{1,256}", self.id):
+                raise ValueError("clap id must be 1..256 printable non-whitespace ASCII characters")
+        return self
+
+
+class ClipArgs(DeviceArgs):
+    slotIndex: int = Field(ge=0, le=15)
+
+
+class ClipCreateArgs(ClipArgs):
+    lengthBeats: int = Field(ge=1, le=4096)
+    name: str = Field(min_length=1, max_length=128)
+
+
+class ClipImportArgs(ClipArgs):
+    path: Nonempty
+
+    @model_validator(mode="after")
+    def validate_path(self):
+        validate_local_path(self.path)
+        return self
+
+
+class NoteWindowArgs(ClipArgs):
+    channel: int = Field(ge=0, le=15)
+    stepSizeBeats: float = Field(ge=1 / 128, le=4)
+    startStep: int = Field(ge=0, le=1048576)
+    steps: int = Field(ge=1, le=128)
+    pitchStart: int = Field(ge=0, le=127)
+    pitchCount: int = Field(ge=1, le=128)
+
+    @model_validator(mode="after")
+    def validate_pitch_window(self):
+        if self.pitchStart + self.pitchCount > 128:
+            raise ValueError("pitchStart + pitchCount must not exceed 128")
+        return self
+
+
+class NoteEdit(StrictModel):
+    op: Literal["set", "clear"]
+    beat: float = Field(ge=0, le=4194304)
+    pitch: int = Field(ge=0, le=127)
+    velocity: Annotated[int, Field(ge=1, le=127)] = omitted()
+    durationBeats: Annotated[float, Field(ge=1 / 128, le=4096)] = omitted()
+
+    @model_validator(mode="after")
+    def validate_operation(self):
+        supplied = self.model_fields_set & {"velocity", "durationBeats"}
+        if self.op == "set" and supplied != {"velocity", "durationBeats"}:
+            raise ValueError("set requires velocity and durationBeats")
+        if self.op == "clear" and supplied:
+            raise ValueError("clear forbids velocity and durationBeats")
+        return self
+
+
+class NoteEditArgs(NoteWindowArgs):
+    edits: list[NoteEdit] = Field(min_length=1, max_length=256)
+
+    @model_validator(mode="after")
+    def validate_edits(self):
+        cells = set()
+        intervals: dict[int, list[tuple[int, int]]] = {}
+        grid = Decimal(str(self.stepSizeBeats))
+        for edit in self.edits:
+            beat = Decimal(str(edit.beat))
+            if beat % grid:
+                raise ValueError("beat must align exactly with stepSizeBeats")
+            step = int(beat / grid)
+            if not self.startStep <= step < self.startStep + self.steps:
+                raise ValueError("edit beat is outside the requested step window")
+            if not self.pitchStart <= edit.pitch < self.pitchStart + self.pitchCount:
+                raise ValueError("edit pitch is outside the requested pitch window")
+            cell = (step, edit.pitch)
+            if cell in cells:
+                raise ValueError("duplicate edit cell")
+            cells.add(cell)
+            if edit.op == "set":
+                duration = Decimal(str(edit.durationBeats))
+                if duration % grid:
+                    raise ValueError("durationBeats must align exactly with stepSizeBeats")
+                end = step + int(duration / grid)
+                if end > self.startStep + self.steps:
+                    raise ValueError("set duration extends beyond the requested step window")
+                spans = intervals.setdefault(edit.pitch, [])
+                if any(step < old_end and start < end for start, old_end in spans):
+                    raise ValueError("same-pitch set durations overlap")
+                spans.append((step, end))
+        return self
+
+
+class TransportSetArgs(StatusArgs):
+    playing: bool = omitted()
+    tempoBpm: Annotated[float, Field(ge=20, le=666)] = omitted()
+    positionBeats: Annotated[float, Field(ge=0)] = omitted()
+    metronome: bool = omitted()
+    loopEnabled: bool = omitted()
+    loopStartBeats: Annotated[float, Field(ge=0)] = omitted()
+    loopDurationBeats: Annotated[float, Field(gt=0)] = omitted()
+
+    @model_validator(mode="after")
+    def require_change(self):
+        if not self.model_fields_set - {"timeoutMs"}:
+            raise ValueError("transport.set requires at least one changed field")
+        if {"loopStartBeats", "loopDurationBeats"} <= self.model_fields_set:
+            if not math.isfinite(self.loopStartBeats + self.loopDurationBeats):
+                raise ValueError("loopStartBeats + loopDurationBeats must be finite")
+        return self
+
+
+class TrackSetArgs(DeviceArgs):
+    name: Nonempty = omitted()
+    volumeNormalized: UnitValue = omitted()
+    panNormalized: UnitValue = omitted()
+    mute: bool = omitted()
+    solo: bool = omitted()
+    arm: bool = omitted()
+
+    @model_validator(mode="after")
+    def require_change(self):
+        if not self.model_fields_set - {"timeoutMs", "trackId"}:
+            raise ValueError("tracks.set requires at least one changed field")
+        return self
+
+
+class TrackCreateArgs(StatusArgs):
+    type: Literal["audio", "instrument", "effect"]
+    position: int = Field(ge=-1, le=2147483647)
+    name: Nonempty
+
+
+class RemotePageArgs(ParameterArgs):
+    contextToken: Nonempty
+    pageIndex: int = Field(ge=0, le=4095)
+    expectedPageName: Nonempty
+
+
+class RemoteSetArgs(ParameterArgs):
+    contextToken: Nonempty
+    expectedPageName: Nonempty
+    parameterIndex: int = Field(ge=0, le=7)
+    expectedParameterName: Nonempty
+    normalizedValue: UnitValue

bitwig_agent/server.py

@@ -0,0 +1,60 @@
+"""MCP stdio adapter over the shared domain catalog and loopback client.
+
+Public SDK APIs: https://github.com/modelcontextprotocol/python-sdk/tree/v1.29.1
+Importing this module does not create a server or configure any global client.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Any
+
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import CallToolResult, TextContent, Tool, ToolAnnotations
+
+from bitwig_agent.catalog import TOOLS, validate_call
+from bitwig_agent.client import BridgeClient, BridgeError, configured_port
+
+
+def create_server(client: BridgeClient | None = None) -> Server:
+    bridge = client if client is not None else BridgeClient(configured_port())
+    server = Server("Bitwig Agent", version="0.1.1", instructions="Discover capabilities and tracks.list first. Our indices are zero-based. Use exact discovered targets and inspect bounded windows and verification. Timeouts are not cancellation; reconcile unknown outcomes before another write. No automatic retries. The agent may use Computer Use for API gaps; never blindly repeat an uncertain write through the GUI.")
+
+    @server.list_tools()
+    async def list_tools() -> list[Tool]:
+        return [
+            Tool(name=name, description=spec.description + " Example arguments: " + json.dumps(spec.examples[0], ensure_ascii=False),
+                 inputSchema=spec.model.model_json_schema(),
+                 annotations=ToolAnnotations(readOnlyHint=spec.read_only, destructiveHint=not spec.read_only, idempotentHint=False))
+            for name, spec in TOOLS.items()
+        ]
+
+    # The shared strict validator also enforces cross-field host invariants.
+    # Handle its errors ourselves so MCP and CLI both return JSON envelopes.
+    @server.call_tool(validate_input=False)
+    async def call_tool(name: str, arguments: dict[str, Any]) -> CallToolResult:
+        try:
+            params, timeout_ms = validate_call(name, arguments)
+            payload = {"result": await bridge.call(name, params, timeout_ms)}
+            failed = False
+        except BridgeError as exc:
+            payload = {"error": exc.error}
+            failed = True
+        except (ValueError, TypeError) as exc:
+            payload = {"error": {"code": "invalid_params", "message": str(exc), "outcome": "not_dispatched"}}
+            failed = True
+        return CallToolResult(content=[TextContent(type="text", text=json.dumps(payload, allow_nan=False, separators=(",", ":")))], structuredContent=payload, isError=failed)
+
+    return server
+
+
+async def run() -> None:
+    server = create_server()
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(read_stream, write_stream, server.create_initialization_options())
+
+
+def main() -> None:
+    asyncio.run(run())

bitwig_agent-0.1.1.dist-info/METADATA

@@ -0,0 +1,98 @@
+Metadata-Version: 2.5
+Name: bitwig-agent
+Version: 0.1.1
+Summary: Thin stdio MCP adapter for the local Bitwig Controller Extension
+Project-URL: Homepage, https://github.com/BANANASJIM/bitwig-agent
+Project-URL: Documentation, https://github.com/BANANASJIM/bitwig-agent/blob/main/INSTALL.md
+Project-URL: Repository, https://github.com/BANANASJIM/bitwig-agent
+Project-URL: Issues, https://github.com/BANANASJIM/bitwig-agent/issues
+Project-URL: Releases, https://github.com/BANANASJIM/bitwig-agent/releases
+License-Expression: MIT
+License-File: LICENSE
+Keywords: audio,bitwig,mcp,midi
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Multimedia :: Sound/Audio :: MIDI
+Requires-Python: >=3.11
+Requires-Dist: mcp<2,>=1.29.1
+Requires-Dist: pydantic<3,>=2.11
+Description-Content-Type: text/markdown
+
+# Bitwig Agent
+
+An experimental Bitwig Controller Extension with Python MCP and CLI tools. Agents can inspect and control tracks, devices and MIDI clips, and author **The Grid** patches through structured tools. Your agent owns planning; this bridge provides bounded controls and observed results, not automatic GUI fallback.
+
+**Tested compatibility:** native evidence is limited to **Linux, Bitwig Studio 6.1.3 / Controller API 25**. macOS, Windows and other Bitwig versions are unverified. Private Grid/modulator access additionally requires the exact mapped host-JAR SHA-256 and fails closed on a mismatch; do not bypass that gate. See [verification and coverage limits](VERIFICATION.md).
+
+**Use a disposable project and keep backups.** The extension listens on unauthenticated `127.0.0.1:61172`: any local process able to connect can control Bitwig. Use a trusted local machine; never expose or forward this port to a network. Never blindly retry an uncertain mutation: a timeout may mean the edit happened. [Targeting and completion safety](USAGE.md#target-safely-then-observe-completion) applies to every write.
+
+## Quickstart
+
+You need your own Bitwig Studio installation, Python 3.11+ and [uv](https://docs.astral.sh/uv/getting-started/installation/). The released wheel and extension need **no Git checkout or JDK**. The commands below use GitHub release assets, not a PyPI package.
+
+### 1. Install
+
+```sh
+uv tool install "https://github.com/BANANASJIM/bitwig-agent/releases/download/v0.1.1/bitwig_agent-0.1.1-py3-none-any.whl"
+bitwig-agent-install
+```
+
+The installer downloads the same-version `BitwigAgent.bwextension` and `SHA256SUMS`, verifies the extension checksum, and installs it in your Bitwig Extensions directory. Different existing bytes are backed up outside Bitwig's extension scan; identical bytes are left untouched. [Custom locations, offline installation and troubleshooting](INSTALL.md).
+
+Prefer this persistent install for an MCP client. [Installation alternatives](INSTALL.md#persistent-uv-tools-and-ephemeral-uvx) cover ephemeral `uvx`, offline assets and the local Arch package recipe. PyPI/AUR publication is separate from GitHub releases; the short index-based commands are not the current installation path.
+
+### 2. Enable in Bitwig
+
+Open **Settings → Controllers → Add controller** and choose vendor **Bitwig Agent**, model **Local API bridge** (controller name **Bitwig Agent**). No MIDI ports are needed. Enable it, open a disposable project, then check the connection:
+
+```sh
+bitwig-agent-rpc status
+```
+
+A successful status response from the running extension establishes connectivity—not successful editing, audio output or persistence. Connection failures report `outcome: not_dispatched` until the endpoint is available. If the controller is absent, check the install destination and restart Bitwig after installing/replacing the extension.
+
+### 3. Connect your MCP client
+
+```sh
+bitwig-agent-install --mcp-config
+```
+
+Copy the printed JSON into your client's MCP server configuration, following that client's instructions, then reload/restart its MCP connection. This command **only prints configuration**; it does not install/download anything or edit your client settings. The generated configuration launches the installed Python environment by absolute path, avoiding GUI applications' often different `PATH`. The adapter uses **stdio**; the client starts it and connects it to the local extension.
+
+[examples/mcp-config.json](examples/mcp-config.json) is a minimal static alternative using the installed `bitwig-agent` command. Prefer generated configuration, especially for GUI clients. See [connection troubleshooting](INSTALL.md#troubleshooting).
+
+## Useful checks
+
+```sh
+bitwig-agent-install --version
+bitwig-agent-rpc list
+bitwig-agent-rpc describe notes.edit
+bitwig-agent-rpc tracks.set --help
+bitwig-agent-rpc status
+```
+
+Version, catalog, schema and help commands work **offline**; they do not demonstrate a Bitwig connection. Only the last command above contacts the extension. Running `bitwig-agent` manually starts a stdio server waiting for an MCP client, not a graphical application or a connection check.
+
+## Documentation
+
+- [Documentation index](docs/README.md): choose an installation, operation, architecture or packaging guide.
+- [Installation](INSTALL.md): persistent uv tools, ephemeral uvx, local Arch package, offline/custom install and troubleshooting.
+- [Usage and safety](USAGE.md): control bounds, targeting, unknown outcomes and the explicit Grid music recipe.
+- [Architecture](docs/architecture.md): Python/Java interfaces, state ownership and why the bridge does not plan.
+- [Protocol](PROTOCOL.md): request/response schemas, limits and side effects.
+- [Verification](VERIFICATION.md): reproducible checks and unresolved native coverage; host-free checks are not native acceptance.
+- [Contributing](CONTRIBUTING.md) and [packaging](docs/packaging.md): source setup, artifacts and release promotion.
+- [Portable agent skill](https://github.com/BANANASJIM/bitwig-agent/tree/main/skills/bitwig-agent): copyable Agent Skills instructions; not permission to operate your DAW.
+- [Security](SECURITY.md): local trust boundary and private vulnerability reporting.
+
+## License
+
+Project code is [MIT licensed](LICENSE). Gson is Apache-2.0; see [third-party notices](THIRD_PARTY_NOTICE.md) and [its license](third-party/GSON-LICENSE.txt). Bitwig Studio and its proprietary host JAR are separate dependencies and are not bundled.

bitwig_agent-0.1.1.dist-info/RECORD

@@ -0,0 +1,13 @@
+bitwig_agent/__init__.py,sha256=07KQ7gXfqsG7st-hqBcT9RVGDAH2f5ui1Lio_WnQ4Yg,73
+bitwig_agent/__main__.py,sha256=ZK2phOuhaMi1uRcgrZ5usrKpx3uxc_iBqkd0wr6venQ,125
+bitwig_agent/catalog.py,sha256=tHDseznVAfvq-qv5ad3Q31UgCxKsQvPr2nVQOEsxTeg,27400
+bitwig_agent/cli.py,sha256=F-XhigpQ-D7B-mdupeAggk1J9-yYrJ650Bj-hI_YSHQ,6025
+bitwig_agent/client.py,sha256=duQTww4YgID5zss322DiTj255bBcuje0WLR7CgiCu1M,5177
+bitwig_agent/install.py,sha256=pKP8WaFyrhbzhoAqwy4-_-1_ciBiaYxLooDEGGKAxlg,5063
+bitwig_agent/schema.py,sha256=Jt8fq3RlQsmChGFHM8wKMzDsOiNnLnFvhah3UB3EIIQ,16345
+bitwig_agent/server.py,sha256=wGZww44Ijs7BaK9wBrFLakJB1ku_F0-V4btYCg-YLsg,2833
+bitwig_agent-0.1.1.dist-info/METADATA,sha256=t8Yb4iQMATcm5aOW7QXwVZsm-zpKv7RxVO1SF0mN_x8,6744
+bitwig_agent-0.1.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+bitwig_agent-0.1.1.dist-info/entry_points.txt,sha256=7P3eP1bMB5NU1cz2MYC1m0HKh1zuoRn06J7fnWEVh9I,148
+bitwig_agent-0.1.1.dist-info/licenses/LICENSE,sha256=6gTlgcTupAGCCELiOc8ZRVT5p0QBoAfo2l1pzd0giso,1067
+bitwig_agent-0.1.1.dist-info/RECORD,,

bitwig_agent-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

bitwig_agent-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+bitwig-agent = bitwig_agent.server:main
+bitwig-agent-install = bitwig_agent.install:main
+bitwig-agent-rpc = bitwig_agent.cli:main

bitwig_agent-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BANANASJIM
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.