zos-api-debug
Skill19 starsChanged 21 days agoApache-2.0View on GitHub
Use when the OptiVibe MCP can't reach OpticStudio — a tool returns an engine/connection/license error (engine_unavailable, engine_connect_timeout, engine_channel_dead, session_closed), OpticStudio won't connect, or the ZOS-API license is rejected. Install / connection / license troubleshooting.
In this repository9 other files it gives its agents.
- AGENTS.mdAGENTS.md
- bench-catalogSkill
- design-aberration-reviewSkill
- design-compareSkill
- design-glass-matchingSkill
- design-reviewSkill
- design-tolerance-desensitizeSkill
- design-vision-reviewSkill
- optimize-loopSkill
The file
Files
ZOS-API Debug — Install / Connection / License Troubleshooting
Overview
The OptiVibe harness drives OpticStudio through the ZOS-API (a typed .NET API reached via pythonnet). When a design-touching tool can't reach the engine it returns a typed error envelope rather than raising — this skill maps those failures to what the USER can fix on their machine (install, architecture, license, a stuck engine). The harness owns the .NET / pythonnet plumbing and reaps its own engine; you do not write connection code.
When to Use
- A design tool returns
error_family: "engine_unavailable"(couldn't acquire or validate the engine) error_family: "engine_connect_timeout"(the engine open wedged)error_family: "engine_channel_dead"or"session_closed"(the engine transport was lost mid-session)- OpticStudio won't launch, or the ZOS-API license is rejected
- The MCP seems stuck on the first design-touching call after a restart
What the user sees
The engine opens LAZILY — the first tool that touches a design takes the single OpticStudio seat. So install, registration, and reference lookups all succeed regardless of license tier; a connection or license failure surfaces only on that first design-touching call, as a typed envelope:
| error_family | Meaning | What to check |
engine_unavailable | The engine couldn't be acquired / validated | OpticStudio installed and licensed for the ZOS-API; 64-bit Python ↔ 64-bit OpticStudio; install path resolvable |
engine_connect_timeout | The open WEDGED (a hung handshake or a stuck orphan) | A prior OpticStudio server may be holding the seat — see "stuck engine" below; then retry |
engine_channel_dead / session_closed | The engine transport was lost mid-session | The OpticStudio process died or was closed. Retrying does not re-open it: restart the MCP server, then reload the design from disk |
Triage
1. Is OpticStudio licensed for the ZOS-API?
A viewer / design-only seat without API entitlement can connect but fails the API
license check (IsValidLicenseForAPI). This is a license/seat problem, not a bug — no
code change fixes it. Confirm the install is licensed for the ZOS-API tier the API
requires.
2. Architecture + install path
- 64-bit Python must match 64-bit OpticStudio (an arch mismatch fails the connection).
- The harness resolves the install directory automatically (env override → registry →
Program Files scan). If resolution fails, set
ZEMAX_DIRto the install folder. - The engine and the ZOS-API .NET surface are Windows-only.
3. A stuck / wedged engine (engine_connect_timeout)
The single seat (N=1) can be held by an orphaned OpticStudio server from an earlier run
— e.g. after Claude Code hard-killed the MCP. The harness reclaims such an orphan on the
next boot (it never touches a concurrent / foreign OpticStudio you are using
interactively). If a first call times out, retry it; if it persists, close any stray
headless OpticStudio.exe that no interactive session owns, then retry.
Environment Checklist
- 64-bit Python matches 64-bit OpticStudio
- OpticStudio installed and licensed for the ZOS-API (
IsValidLicenseForAPI) - Install path resolvable (else set
ZEMAX_DIR) - No orphaned headless OpticStudio server holding the single seat
- Windows (the ZOS-API .NET surface is Windows-only)
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

