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.

Existing APIs first

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.

Submit once, observe durablyPYTHON
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))
  • submit preflights the dialog guard and records an unknown outcome instead of submitting twice.
  • After a reconnect or daemon restart, re-establish observation with mgr.list() or mgr.load(run_id) plus mgr.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).
No automatic resubmission

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.

Inspect, guard, preparePYTHON
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:

Authorized answerPYTHON
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.

  1. Inspect read-only first.
  2. Show the preview and ask the user before an ambiguous dialog.
  3. Never answer a simulation-start or save dialog without authorization.
  4. 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

SignalMeaningAction
EXPLORER-2406The 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 changesThe 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.

Confirm before unlocking

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.

  1. Write batch.py in the workspace with the normal file tool.
  2. Run it with path: "batch.py". Each run copies the current file into a fresh job directory.
  3. 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.

  1. Run the printed load("...") line in the CIW (Virtuoso Command Interpreter Window) when the state is waiting. SSH (Secure Shell) login and the tunnel are already up. Nothing answers on the daemon port until that setup loads.
  2. Start a fixed-port connection and let the probe attach a signed daemon. attach.attached records the reuse, and no deployment or CIW load is needed.
  3. Run deploy_daemon when daemonProbe reports no-listener or legacy, then load the returned load("...") line in the intended idle CIW. Start again afterward. A reconnect or restart does not deploy files or reload the setup.
  4. 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, path and a hint. A missing scratch root under the home is created. A missing path elsewhere names the required mkdir -p -m 700.
  5. Run test_connection when 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:

Explicit CIW readPYTHON
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 MaestroJobManager status 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.
Unknown is not failed

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.