tdmcp-bridge-endpoint — the bridge vertical slice

A bridge feature is correct only when four layers agree on one shape: the Python route, the TS client method, the Zod validator, and the tool that consumes it. This skill is that contract. Build the slice top-to-bottom, keep an exec fallback so it ships safely before every bridge in the wild updates, and prove it all offline.

Run bridge slices one at a time — they share touchDesignerClient.ts, validators.ts, and the bridge route registry. Two in parallel is merge hell.

Why exec→REST at all

The bridge runs arbitrary Python on /api/exec. A security-conscious VJ runs TDMCP_BRIDGE_ALLOW_EXEC=0 on a venue network — and ~69 tools silently die. Promoting a well-defined op (connect, param-mode read/write, DAT text, node flags, logs) to its own REST route makes it survive that hardened config. You are promoting proven logic, not inventing it — start from the Python the tool already sends through /api/exec.

The slice, in order

1. Bridge (Python, td/)

• Add a handler module (or extend the right existing one) and register the route. Find how routes are registered (the request dispatcher in td/) and follow that exact pattern — don't invent a second mechanism.
• Keep every TD-global (op, app, project, ui) inside the handler function so the module imports cleanly outside TD (the tests rely on this).
• Return a JSON report with a stable shape: a top-level ok/error and the data. Mirror the envelope the existing endpoints return so parsePythonReport/the validators stay uniform.
• Honor TDMCP_BRIDGE_TOKEN (bearer auth) and the ALLOW_EXEC gate exactly as sibling routes do — a new route must not become an auth bypass.
• python3 -m py_compile td/**/<changed>.py on every changed file.

2. Client method (src/td-client/touchDesignerClient.ts)

• Add one typed method that calls the new route (GET/POST/PATCH/PUT as fits).
• Map failures to the existing typed errors: TdApiError (4xx/5xx with a body), TdConnectionError (refused/DNS), TdTimeoutError. Never let a raw fetch error escape.
• Exec fallback: if the endpoint returns 404 (older bridge without the route), fall back to the previous /api/exec Python path. This is what lets the promotion ship before the bridge is reinstalled everywhere. Make the fallback a private helper so the test can force both paths.

3. Validator (src/td-client/validators.ts)

• Add a Zod schema for the response envelope and .parse() it in the client — never hand a raw wire object upward. Reuse the shared envelope helpers already in the file.

4. Rewire the tool(s)

• Point connect_nodes/disconnect_nodes/read_parameter_modes/ set_parameter_expression/edit_dat_content/set_dat_content/get_bridge_logs/ the node_detail consumers at the new method. Preserve current behavior and output exactly — this is a transport swap, not a redesign. Keep fail-forward: validate inputs with Zod, turn TD failures into friendly isError via errorResult/friendlyTdError; never throw out of a handler.

Probe-live discipline (when TD is offline)

Attribute names that vary by TD build are the trap: connector semantics for connect/disconnect, ParMode/.expr/.mode names for param-modes, Error DAT column layout for logs, optype enumeration for createable. The backlog flags these probe-live.

• TD reachable (get_td_info ok): probe the real names in a scratch network first (create a couple of ops, read the actual attrs), then lock the schema.
• TD offline: implement against the best-known names from the knowledge base (tdmcp://operators/..., tdmcp://classes/...) and TD's documented Python API; write the offline tests; and flag every probe-dependent assumption UNVERIFIED-live in your report (with the source you used). Do not claim a live pass you could not observe. The campaign-lead holds UNVERIFIED-live items for a live pass before the final release.

Tests (offline — no TD)

• Bridge unittest td/tests/test_<name>.py: import the handler, call it with a faked op()/payload, assert the report shape and the error branch. At minimum py_compile. Run python3 -m unittest discover -s td/tests.
• Client msw test tests/unit/*: stub the route; assert (a) success → validated shape, (b) 4xx/5xx → correct TdError subclass, (c) timeout → TdTimeoutError, (d) 404 → exec-fallback path returns the same shape. Mirror the closest existing client test.

Gates (all green before reporting)

npm run typecheck · npm run build · ./node_modules/.bin/biome check . (NOT npm run lint) · npm test · npm run test:bridge. Fix forward; never disable a gate or use --no-verify.

Report back

Endpoint(s) added + method + validator; tool(s) rewired; the exec-fallback behavior; every UNVERIFIED-live assumption with its source; gate results; and the ledger fields to set (files[], status). On a re-run, treat feedback as a diff — don't rewrite a green slice.