SDT/docs/gui-bridge-contract.md

GUI Bridge Contract (sdt bridge --stdio)

The GUI uses a hybrid bridge:

• execution: sdt run/debug --json (streamed)
• read/manage: sdt bridge --stdio JSON-RPC over stdio

Envelope

Request (one JSON object per line):

{ "id": "req-1", "method": "workspace.get", "params": { "projectRoot": "E:\\repo" } }

Response:

{ "id": "req-1", "ok": true, "result": { "...": "..." }, "error": null }

Error response:

{
  "id": "req-1",
  "ok": false,
  "result": null,
  "error": { "code": "validation_failed", "message": "Missing required parameter 'filePath'." }
}

Methods (v1)

• workspace.get
• workspace.add (candidatePath, initializeConfig)
• favorites.list
• favorites.toggle (favoriteProjectPath, workflowId, label)
• favorites.removeMany (items[] with projectPath, workflowId)
• history.list (limit)
• events.listFiles
• events.readFile (filePath)
• envProfiles.list
• envProfiles.resolve (envProfile)
• envProfiles.setActive (profileId)
• envProfiles.saveProfile (profile object with id, description, inherits[], values{})
• envVars.list
• envVars.save (env[] array of env var definitions)
• doctor.run
• setup.plan (read-only preview)
• setup.autofixDirs (apply missing directory fixes)
• setup.migrateLegacy (apply targets->workflows migration)
• setup.applyRecommendedConfig (apply recommended config updates with backup)

Determinism Notes

• Responses are always single-envelope JSON.
• Unknown methods return method_not_found.
• Parameter issues return validation_failed.
• GUI should tolerate additive fields in result.