04 · Practice
Agent workflows
These recipes use APIs that already ship in virtuoso-bridge-lite. They keep a Maestro run observable, inspect a dialog before you answer it, and handle an uncertain outcome without resubmitting work.
The working principle
The plugin exposes the bridge; the bridge owns the logic. Do not add a plugin-side Maestro runner, job store, dialog manager, history manager, point counter or scheduler. Each recipe below uses an existing entry point: MaestroJobManager, client.dialogs, x11.dismiss_window, the save and history calls, and the job-policy calls.
Read the exact signatures from the installed package before you call. virtuoso_bridge_api action describe answers from the installed bridge, so you see what exists. If a recipe needs a capability the bridge lacks, report the gap. Do not wrap raw Cadence SKILL (the Virtuoso scripting language) or shell commands around it.
The installed bridge is the source of truth for signatures and behavior. Describe the target, then call it. Do not guess flags, method names or return shapes.
Long Maestro runs
Use MaestroJobManager when a run may outlive a tool call or the daemon may restart. It submits the job once and lets you observe it.
from virtuoso_bridge.virtuoso.maestro.jobs import MaestroJobManager
mgr = MaestroJobManager.from_client(client)
job = mgr.submit(session="mySession", run_id="run-001", timeout=180)
status = mgr.status(job) # poll this; it is persisted locally/remotely
print(status)
print(mgr.log(job, lines=80))
submitpreflights the dialog guard and records an unknown outcome instead of submitting twice.- After a reconnect or daemon restart, re-establish observation with
mgr.list()ormgr.load(run_id)plusmgr.reconcile(job)before any retry. - The API has no job-cancel method. Do not invent one.
- Save dirty setup before you submit:
client.maestro.save_setup(lib, cell, session=session).
A lost connection is an unknown outcome. Reconcile the existing job before you decide anything. Submitting the same run again can duplicate the work.
Dialogs
Inspection and guard are existing APIs. Inspect read-only first, then prepare a close ticket for the window you mean.
report = client.dialogs.inspect(pid=client.remote_virtuoso_pid)
report = client.dialogs.enable_guard(pid=client.remote_virtuoso_pid,
protect_inflight=True)
ticket = client.dialogs.prepare_close(
report.dialogs[0].window_id,
expected_title=report.dialogs[0].title,
)
client.dialogs.close() sends the window-manager close action. It is not a way to press Yes/No on a question dialog.
For an explicitly authorized Yes/No/OK action, use the existing X11 helper:
from virtuoso_bridge.virtuoso import x11
results = x11.dismiss_window(
client.ssh_runner,
"<remote-user>",
window_id,
action="alt-y", # alt-y, alt-n, alt-o, enter, escape
display=":0",
pid=client.remote_virtuoso_pid,
)
print(results) # closure_confirmed / still_mapped
The actions are alt-y, alt-n, alt-o, enter and escape. The result reports closure_confirmed or still_mapped. If the result is uncertain, do not repeat the input.
- Inspect read-only first.
- Show the preview and ask the user before an ambiguous dialog.
- Never answer a simulation-start or save dialog without authorization.
- Verify closure; do not repeat input when the result is uncertain.
The plugin predeploys and verifies the X11 helper when a remote runtime starts. If it is missing later, call the existing x11.dismiss_window API. Its helper upload is part of virtuoso-bridge, not a new plugin function.
History and setup conflicts
| Signal | Meaning | Action |
|---|---|---|
EXPLORER-2406 | The requested history name already exists. | Do not resubmit. Inspect the history, then use the history APIs or an explicit SKILL rename. |
MaestroMonteCarloError: unsaved or unknown setup changes | The Maestro setup is dirty or unknown. | Call client.maestro.save_setup(...), then retry. |
The existing history calls are get_history, lock_history, unlock_history and set_history_lock. A locked history may cause the next ADE Explorer (Analog Design Environment Explorer) run to reuse its name. Unlock or rename only after you confirm the old results are safe.
A locked history affects the next ADE Explorer run. Inspect the existing history, and confirm the old results are safe before you unlock or rename it.
Large runs and job policy
A warnWhenSimsExceed question is Cadence policy, not a bridge failure. Inspect the dialog and show the user what it asks. Answer only after authorization.
For parallel execution, use the existing Maestro job-policy APIs: maeGetJobPolicy / maeSetJobPolicy, or client.maestro.set_job_policy. Do not add a plugin scheduler. Confirm the actual point count and host capacity before a large run. If the policy signature is unfamiliar, describe client.maestro first.
Script source: a file or inline code
virtuoso_bridge_script action run takes exactly one source: inline code, or path to a Python file. Jobs are independent, so there is no fixed scratch script. Use whichever fits the call.
- Write
batch.pyin the workspace with the normal file tool. - Run it with
path: "batch.py". Each run copies the current file into a fresh job directory. - Edit the file after a failure or a measurement, then run it again. The next run reads the edited body.
When you will revisit the script, this loop is usually cheaper than resending the body. The code stays reviewable in the workspace, and an edit does not resend the whole script. Inline code is simpler for a one-off probe.
Connection startup
Read the runtime state instead of guessing from a single log line. virtuoso_bridge_runtime action status reports stage, daemon, daemonProbe, setupHint, attach and error. The state names show which layer is missing, so you do not redeploy or restart blindly.
- Run the printed
load("...")line in the CIW (Virtuoso Command Interpreter Window) when the state iswaiting. SSH (Secure Shell) login and the tunnel are already up. Nothing answers on the daemon port until that setup loads. - Start a fixed-port connection and let the probe attach a signed daemon.
attach.attachedrecords the reuse, and no deployment or CIW load is needed. - Run
deploy_daemonwhendaemonProbereportsno-listenerorlegacy, then load the returnedload("...")line in the intended idle CIW. Start again afterward. A reconnect or restart does not deploy files or reload the setup. - Treat a timed-out browser request as pending, not failed. Deployment runs over SSH and can outlive a short status-poll budget. A deploy error carries
errorCode,pathand ahint. A missing scratch root under the home is created. A missing path elsewhere names the requiredmkdir -p -m 700. - Run
test_connectionwhen you need the checks without a running runtime. It reports SSH, remote Python, the scratch root and the daemon.
A first IL load that fails with load: can't access file - ~/... means a ~-prefixed path reached Virtuoso. load() does not expand ~. Use an absolute remoteScratchRoot on the remote account, or keep ~/ and let the plugin resolve it. Deployment and client/IL uploads never pass ~ to load().
CIW diagnostics
Read the CIW block first. CDF callback failures, *WARNING* lines and SKILL *Error* text land there, not in the returned value, so the block often explains a call that did nothing.
A virtuoso_bridge_api call and a settled virtuoso_bridge_script job attach the block when the CIW printed something during the call. The tool reference covers the block shape, its best-effort caveats and the ciwReport toggle.
When the block is missing or too late, read the CIW explicitly. Force the warning port out, then tail the newest session log:
client.execute_skill('warn("") getWarn()')
log = client.run_shell_command(
'set log = `ls -t ~/CDS.log* | head -1` ; tail -n 40 "$log"')
print(log.output)
run_shell_command runs csh in the Virtuoso process environment, so .output holds the command's stdout and stderr. Do not run it in a loop for every call. The automatic block is cheaper.
Failure rules
- A socket error or daemon drop means the outcome is unknown, not failed. Check the job with
MaestroJobManagerstatus or reconcile, and inspect the history on the host. Never resubmit automatically. - A modal dialog can block SKILL while the simulation still runs. Inspect dialogs out of band with X11. Do not restart the daemon or resubmit because a SKILL poll timed out.
- Prefer existing structured APIs to package-source introspection or raw shell guesses.
When the connection dropped mid-run, the honest state is unknown. Reconcile the job or inspect the history before any retry, and report what was actually observed.