Skip to content

Commit 9dc8b3d

Browse files
jnipligjniplig
authored
[codex] add windows smoke test workflow (#2)
* add windows smoke test workflow * add poc 02 status monitor plan
1 parent d0b01b6 commit 9dc8b3d

8 files changed

Lines changed: 700 additions & 0 deletions

‎docs/install-notes-windows.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# Windows Install Notes
2+
3+
## Current Validated Behavior
4+
5+
- Validated on the ASUS machine with Ableton Live `12.3.6`.
6+
- `ClaudeMCP_Remote` did not become selectable when copied only into the user-level Ableton library path.
7+
- On this machine, Ableton discovered the script only after it was copied into:
8+
9+
```text
10+
C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\ClaudeMCP_Remote
11+
```
12+
13+
- After installation, the script still had to be selected manually in `Options > Preferences > Link, Tempo & MIDI`.
14+
- The script then logged successful startup and exposed a TCP listener on `127.0.0.1:9004`.
15+
16+
## Recommended Install Procedure
17+
18+
1. Close Ableton Live.
19+
2. Open PowerShell as Administrator if the `ProgramData` directory requires elevation.
20+
3. From the repo root, run:
21+
22+
```powershell
23+
.\scripts\windows\deploy_control_surface.ps1
24+
```
25+
26+
4. Start Ableton Live.
27+
5. Open `Options > Preferences > Link, Tempo & MIDI`.
28+
6. Pick `ClaudeMCP_Remote` in an empty `Control Surface` slot.
29+
7. Leave `Input` and `Output` unset unless another test explicitly requires them.
30+
31+
## Verify Startup
32+
33+
Check the Ableton log:
34+
35+
```powershell
36+
Get-Content "$env:APPDATA\Ableton\Live 12.3.6\Preferences\Log.txt" -Tail 200
37+
```
38+
39+
Expected startup lines include:
40+
41+
- `Socket server started successfully on port 9004`
42+
- `ClaudeMCP Remote Script initialized (Queue-based, Thread-Safe)`
43+
- `Socket server listening on port 9004`
44+
45+
## Verify Listener
46+
47+
```powershell
48+
Get-NetTCPConnection -LocalPort 9004 -ErrorAction SilentlyContinue | Format-Table -AutoSize LocalAddress,LocalPort,State,OwningProcess
49+
```
50+
51+
Expected result:
52+
53+
- `127.0.0.1 9004 Listen <pid>`
54+
55+
## Verify With Smoke Test
56+
57+
```powershell
58+
.\scripts\windows\run_smoke_test.ps1
59+
```
60+
61+
That wrapper runs the read-only smoke client and writes raw request/response output under `logs\`.
62+
63+
## Operational Notes
64+
65+
- On this machine, Windows-native runtime validation is more reliable than WSL for socket checks against Ableton.
66+
- Treat WSL as the editing environment and Windows PowerShell as the runtime validation environment.
67+
- Do not modify core Remote Script files for installation-only troubleshooting unless later evidence requires it.

‎docs/poc-01-session-bootstrapper.md‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
# POC 01: Session Bootstrapper
2+
3+
## Objective
4+
5+
Establish a minimal, additive validation path that proves the `ClaudeMCP_Remote` Control Surface loads in Ableton Live, starts its localhost TCP server, and responds to at least one read-only request from an external client.
6+
7+
## Scope
8+
9+
- Install or verify the existing `ClaudeMCP_Remote` folder in Ableton's User Library Remote Scripts path on Windows.
10+
- Select `ClaudeMCP_Remote` as an Ableton Control Surface.
11+
- Confirm that Ableton listens on `127.0.0.1:9004`.
12+
- Run `scripts/poc/smoke_test_client.py` using read-only actions only.
13+
- Capture raw request and raw response output for review.
14+
15+
## Non-goals
16+
17+
- No bootstrapper logic beyond smoke validation.
18+
- No live-performance workflow logic.
19+
- No edits to `ClaudeMCP_Remote/__init__.py`.
20+
- No edits to `ClaudeMCP_Remote/liveapi_tools.py`.
21+
- No changes to the hard-coded action router.
22+
- No attempt to validate all advertised tools.
23+
24+
## Inputs
25+
26+
- Local fork checkout on the ASUS machine.
27+
- Ableton Live installed on Windows.
28+
- Existing Remote Script source under `ClaudeMCP_Remote/`.
29+
- Smoke client at `scripts/poc/smoke_test_client.py`.
30+
- Ableton log file at `%APPDATA%\Ableton\Live x.x.x\Preferences\Log.txt`.
31+
32+
## Outputs
33+
34+
- Evidence that Ableton loaded the Control Surface without obvious startup errors.
35+
- Evidence that `127.0.0.1:9004` is listening while Ableton is running.
36+
- Raw request and raw response output from a read-only smoke test.
37+
- A simple pass/fail result for this phase.
38+
39+
## Proposed Command Sequence
40+
41+
```powershell
42+
cd C:\path\to\ableton-liveapi-tools-fork
43+
python scripts\poc\smoke_test_client.py --host 127.0.0.1 --port 9004 --log-file logs\smoke-test-session.txt
44+
```
45+
46+
Optional explicit single-action probe:
47+
48+
```powershell
49+
python scripts\poc\smoke_test_client.py --action ping --log-file logs\smoke-test-ping.txt
50+
```
51+
52+
Optional listener check before the client run:
53+
54+
```powershell
55+
netstat -ano | findstr 9004
56+
```
57+
58+
## Verification Steps
59+
60+
1. Confirm `ClaudeMCP_Remote` is present under the Ableton User Library Remote Scripts directory.
61+
2. Launch Ableton Live and select `ClaudeMCP_Remote` in Preferences > Link, Tempo & MIDI > Control Surface.
62+
3. Open the Ableton log and confirm there is no immediate `ClaudeMCP` startup exception.
63+
4. Confirm a localhost listener exists on port `9004`.
64+
5. Run the smoke client and verify that the first action is read-only.
65+
6. Review the captured raw request and raw response output in the chosen log file.
66+
67+
## Risks
68+
69+
- Upstream install docs appear to overstate autoloading; manual Control Surface selection is likely required.
70+
- The protocol is inferred from repo code and examples, not from a formal spec.
71+
- Ableton can load the Control Surface but still fail to bind the socket if the port is already in use.
72+
- `get_session_info` is read-only but still depends on the main-thread queue path being healthy.
73+
- The Ableton log location varies by installed version string.
74+
75+
## Pass/Fail Criteria
76+
77+
Pass:
78+
79+
- Ableton loads `ClaudeMCP_Remote` without obvious startup failure.
80+
- Port `9004` is listening on `127.0.0.1`.
81+
- The smoke client sends a read-only request first.
82+
- The smoke client receives valid JSON with `"ok": true`.
83+
- Raw request/response output is saved for review.
84+
85+
Fail:
86+
87+
- Ableton cannot load or select the Control Surface.
88+
- No listener appears on port `9004`.
89+
- The client cannot connect or times out.
90+
- The response is empty, malformed, or returns `"ok": false`.
91+
92+
## Rollback Approach
93+
94+
- Deselect `ClaudeMCP_Remote` in Ableton Preferences and switch the Control Surface slot back to `None`.
95+
- Remove or rename the installed `ClaudeMCP_Remote` directory from the Ableton User Library Remote Scripts path if needed.
96+
- Delete only the smoke-test log files created under `logs/`.
97+
- Leave core repo files unchanged, since this phase is additive only.

‎docs/poc-02-status-monitor.md‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
# POC 02: Status Monitor
2+
3+
## Objective
4+
5+
Define a minimal, additive status-monitor layer that improves confidence in `ClaudeMCP_Remote` runtime health without modifying the core Remote Script, the 220-action router, or any live-performance behavior.
6+
7+
## Scope
8+
9+
- Build on the validated Windows smoke-test workflow from POC 01.
10+
- Focus on read-only runtime signals already exposed by the repo and the host environment.
11+
- Standardize how to confirm that the Control Surface loaded, the TCP server is listening, and basic session health can be queried safely.
12+
- Capture evidence from both Ableton logs and TCP responses for later review.
13+
14+
## Non-goals
15+
16+
- No edits to `ClaudeMCP_Remote/__init__.py`.
17+
- No edits to `ClaudeMCP_Remote/liveapi_tools.py`.
18+
- No changes to the static action router.
19+
- No event subscription or observer subsystem.
20+
- No attempt to stream real-time session state.
21+
- No live-performance automation, transport control, or write actions.
22+
23+
## Current Known Signals
24+
25+
From repo inspection and runtime validation, the following read-only signals already exist:
26+
27+
- Ableton log messages emitted through `c_instance.log_message(...)`.
28+
- Startup log lines including:
29+
- `Socket server started successfully on port 9004`
30+
- `ClaudeMCP Remote Script initialized (Queue-based, Thread-Safe)`
31+
- `Socket server listening on port 9004`
32+
- `Client connected from ...`
33+
- TCP listener on `127.0.0.1:9004`.
34+
- Read-only TCP actions:
35+
- `ping`
36+
- `health_check`
37+
- `get_session_info`
38+
39+
## Proposed Monitor Surface
40+
41+
The status monitor for this phase should be a wrapper-level workflow, not a new core feature.
42+
43+
### Layer 1: Process and startup evidence
44+
45+
- Confirm Ableton Live is running.
46+
- Confirm `ClaudeMCP_Remote` is selected as a Control Surface.
47+
- Confirm recent Ableton log lines show successful script startup rather than an import or bind failure.
48+
49+
### Layer 2: Listener evidence
50+
51+
- Confirm Windows shows `127.0.0.1:9004` in `Listen` state.
52+
- Record the owning process ID when available.
53+
54+
### Layer 3: Read-only protocol evidence
55+
56+
- Run `ping` to prove command/response flow works.
57+
- Run `health_check` to capture:
58+
- `ok`
59+
- `message`
60+
- `tool_count`
61+
- `ableton_version`
62+
- `queue_size`
63+
- Run `get_session_info` to capture:
64+
- playback state
65+
- tempo
66+
- time signature
67+
- track count
68+
- scene count
69+
- loop values
70+
71+
### Layer 4: Evidence capture
72+
73+
- Save raw request and raw response payloads.
74+
- Save a short Ableton log extract around startup and the client connection event.
75+
- Keep outputs timestamped for side-by-side review across runs.
76+
77+
## Proposed Artifacts
78+
79+
This phase does not require core-code changes. The likely additive outputs are:
80+
81+
- a small Windows-native wrapper script for repeated status checks
82+
- a status log file under `logs/`
83+
- a short runbook section or dedicated doc for interpreting the captured signals
84+
85+
The current repo already includes most of the needed pieces:
86+
87+
- `scripts/windows/run_smoke_test.ps1`
88+
- `scripts/poc/smoke_test_client.py`
89+
- `docs/smoke-test-runbook.md`
90+
91+
## Proposed Command Sequence
92+
93+
```powershell
94+
.\scripts\windows\deploy_control_surface.ps1
95+
```
96+
97+
Restart Ableton Live, select `ClaudeMCP_Remote`, then run:
98+
99+
```powershell
100+
.\scripts\windows\run_smoke_test.ps1
101+
```
102+
103+
Optional direct checks:
104+
105+
```powershell
106+
Get-NetTCPConnection -LocalPort 9004 -ErrorAction SilentlyContinue | Format-Table -AutoSize LocalAddress,LocalPort,State,OwningProcess
107+
Get-Content "$env:APPDATA\Ableton\Live 12.3.6\Preferences\Log.txt" -Tail 200
108+
```
109+
110+
## Verification Steps
111+
112+
1. Confirm Ableton starts without obvious Control Surface load errors.
113+
2. Confirm `127.0.0.1:9004` is in `Listen` state from Windows.
114+
3. Run the smoke-test wrapper and confirm the first action remains read-only.
115+
4. Confirm `ping`, `health_check`, and `get_session_info` all return valid JSON with `"ok": true`.
116+
5. Review the raw request/response capture and the recent Ableton log tail together.
117+
6. Confirm the captured `tool_count` and `ableton_version` remain plausible across repeated runs.
118+
119+
## Risks
120+
121+
- This repo still has no event-driven status feed, so the monitor is polling-based and coarse.
122+
- `health_check` is useful but limited; it reports queue size and version, not full runtime internals.
123+
- WSL-side socket visibility was unreliable on this machine, so status checks must be treated as Windows-native.
124+
- The exact Ableton log path can vary by installed version.
125+
- A successful listener check does not guarantee every action path is implemented correctly.
126+
127+
## Pass/Fail Criteria
128+
129+
Pass:
130+
131+
- Ableton startup evidence is present in the log.
132+
- Windows shows `127.0.0.1:9004` listening.
133+
- Read-only status requests succeed consistently.
134+
- Raw request/response and log evidence are captured together.
135+
- No core Remote Script changes are required for the monitor workflow.
136+
137+
Fail:
138+
139+
- The script does not load or does not stay loaded.
140+
- The port is not listening.
141+
- Read-only requests fail, time out, or return malformed JSON.
142+
- The monitoring workflow depends on WSL-only checks that do not reflect the real Windows runtime.
143+
144+
## Rollback Approach
145+
146+
- Deselect `ClaudeMCP_Remote` in Ableton Preferences if needed.
147+
- Remove the deployed control surface copy from the Ableton scripts directory if this POC must be backed out.
148+
- Delete only additive logs and wrapper outputs.
149+
- Leave core repo code unchanged.
150+
151+
## Recommendation
152+
153+
Proceed with POC 02 as a documentation-and-wrapper phase first. Do not introduce a new monitoring subsystem in the Remote Script until repeated Windows-native runs show a stable need for more granular observability.

0 commit comments

Comments
 (0)