03 · API

Agent tools

Four tools connect an agent to the installed bridge. One manages runtimes and connections, one describes and calls the Python API, one runs batched Python, and one installs and repairs the environment.

The four tools

All four tools are registered on the Host, so every conversation of the profile can use them. Runtimes are process-wide: a fork, a new conversation or a subagent session shares the same tunnel and daemon.

ToolOne-line purposeUse it when
virtuoso_bridge_runtimeManage tunnels, daemons and saved server connections.You need state, a start/stop, a health test, instance discovery or a daemon deployment.
virtuoso_bridge_apiDescribe and call any public virtuoso-bridge target.You know the bridge method you need and want one structured call.
virtuoso_bridge_scriptRun Python in a fresh virtual environment (venv) process with the client connected.The work needs a loop, several calls, measurements or a persisted result.
virtuoso_bridge_setupInstall, update, diagnose and configure the isolated venv.The environment is missing, broken or deliberately changed.

The tools add no Maestro runner, job store, dialog manager, history manager or scheduler. Each is a thin surface over the bridge and the Host's managed runtime. An upstream capability is reached through describe and call, not through a plugin wrapper.

Runtime tool

virtuoso_bridge_runtime takes one required action and the arguments it needs. connection is an id or a name. Omit it to use the default connection. runtime (rt_...) selects one managed runtime when a connection has several. The tool also owns the SSH (Secure Shell) tunnel and the sidecar.

ActionWhat it does
statusReturn a compact projection of setup, connections, runtimes, attached agents and running actions.
listReturn the same projection for every connection and runtime in the profile.
startCreate or reuse the managed SSH tunnel, connect the sidecar and attach a signed daemon when one answers.
stopTear down the tunnel and sidecar for that runtime.
restartStop and start the runtime again. It does not deploy files or reload the setup in the CIW (Virtuoso Command Interpreter Window).
pingAsk the running sidecar for a fresh status snapshot.
connectionsList saved connection profiles.
save_connectionCreate or update a connection from connectionConfig, with write-only secret credentials.
delete_connectionRemove a saved connection.
test_connectionReturn a layered health report for SSH, remote Python, the scratch root and the daemon.
instancesDiscover automatic-session instances with an optional timeoutSec budget (default 20).
select_instanceStore a discovered daemon port on the connection before a restart.
deploy_daemonPrepare and upload the account bootstrap, then return its load("...") line.
detect_shellRun the Cadence environment script under csh and sh, and cache which one exposes virtuoso.
host_keyProbe the SSH host keys and report fingerprints, known and unknown entries, and conflicts.
trust_hostWrite one user-confirmed fingerprint to known_hosts, and accept only a key the fresh probe offered.
orphansList tunnels left behind by a crashed DeepSeek Harness (DSH) process.
stop_orphanStop one orphaned tunnel.

The compact status projection

status and list return a compact projection, not the full dashboard state. It covers setup readiness and source, SSH backends, connection endpoints, runtime state and stage. It also covers the daemon state (ready, no-response, auth-failed, unreachable, unknown) and the daemonProbe result. The rest covers the selected instance (port, Virtuoso pid, work directory), attach.attached, setupHint, the error, attached agents and running actions.

Verbose install logs, source and venv debug paths, tunnel internals and full tracebacks stay in the UI, which keeps the full state. A fixed-port start that attached a live daemon reports attach.attached. A setupHint appears only before first readiness, so a healthy connection shows no CIW prompt.

Status, then a startJSON
{"action": "status", "waitMs": 15000}
{"action": "start", "connection": "lab-virtuoso"}

waitMs is a wait budget for status, start and ping (default 15000). status waits for an in-flight start to settle, or returns a pending snapshot when the budget expires.

Instances and sub-instances

With autoSessions, the daemon takes an OS-assigned port, so a connection binds to a discovered instance instead of a fixed port. instances performs read-only discovery. Nothing is selected until select_instance stores a port. A missing selection or several matching instances fails with the available list instead of silently picking one.

Discover and selectJSON
{"action": "instances", "connection": "lab-virtuoso", "timeoutSec": 20}
{"action": "select_instance", "connection": "lab-virtuoso", "port": 65142}
{"action": "restart", "connection": "lab-virtuoso"}

Workdir sub-instances start with subInstance on start or restart: an id, a name or an absolute remote work directory. Each sub-instance has its own VBL (virtuoso-bridge-lite) profile and sidecar and is discovered by workdir. One connection can therefore cover several project CIWs without fixed ports. workDir filters discovery by an absolute remote working directory.

Deploying and testing

A fixed-port start probes the daemon port first and attaches a signed daemon, so you do not deploy or load setup for a live daemon. deploy_daemon prepares the generated account bootstrap without connecting. It starts no tunnel or daemon, and it never loads SKILL (Virtuoso's scripting language).

A differing remote bundle is not overwritten. The result reports both versions, and replace: true is the explicit upgrade path. A shared setup configured through daemonSetup or installed with virtuoso-bridge install-daemon is read-only to clients and is never replaced. A fixed legacy deployment carries recommendedAutoSessions, because such a daemon is not discoverable after a CIW restart.

Explicit replacementJSON
{"action": "deploy_daemon", "connection": "lab-virtuoso", "replace": true}

test_connection returns a structured report with ssh, remotePython, scratchRoot and a signed/unsigned daemon probe. It also runs while the runtime is stopped. It is not an SSH ping. It never deploys or creates the scratch root, and the card marks the target ready only when both SSH and a signed daemon pass. A running runtime's Host-owned tunnel is reused. A stopped runtime gets a short-lived probe tunnel. A Paramiko session never launches ssh.exe.

Connection writes and approval

save_connection creates a row when neither its id nor its name matches an existing connection. Saving without an id under an existing name updates that row instead of creating a duplicate, and the result says created or updated. An existing row is retargeted when host, user, sshPort, jumpHost/jumpUser or a role host changes.

Creating a connection, or changing an existing row's SSH target, modifies something outside the workspace. A saved connection is a standing grant that opens a shell, Python and SKILL on that account. The tool asks for approval through DSH's permission card unless the session has Full access. A rejected or unavailable approval is final. Saves that repeat the same SSH target with notes, scratch roots, sub-instances or environment need no prompt.

In fixed mode, leaving port blank derives the stable per-user daemon port from the SSH user name (SHA-1, range 65000–65499). In automatic mode port is unused and stays unset. Daemon tokens are write-only: pass them in secret, and they are stored through DSH credentials instead of the connection JSON.

Never work around a rejection

If approval is rejected or unavailable, create the row on the configuration page instead. Do not edit plugin settings by hand to bypass the permission card.

API tool

virtuoso_bridge_api lets you read and call the installed bridge without guessing a signature. describe has three zoom levels plus a method lookup. Its answers follow the installed version, so newer layout, Maestro and dialog helpers appear without a plugin update.

Describe formAnswer
describeReturn a compact index of targets, documented classes and a hint to describe one.
describe target=client.schematicList that target's methods as name(signature) -> return, with short summaries, properties and child targets.
describe target=client.schematic method=open_windowReturn exactly one method with its full docstring and parameter table.
describe method=open_windowList the targets that define that method.
Describe, then callTEXT
virtuoso_bridge_api action=describe
virtuoso_bridge_api action=describe target=client.layout
virtuoso_bridge_api action=describe target=client.schematic method=open_window
virtuoso_bridge_api action=describe method=open_window

An answer that exceeds the inline budget (about 14,000 characters) is not cut off. The full payload is written as JSON under <cache dir>/results/, and the reply ends with that path. Read or grep it, then clear it with virtuoso_bridge_setup action=clear_cache cache=results. Large call results follow the same rule.

Callable targets

call invokes one method on one of the public targets:

  • client — the connected client itself, including execute_skill and run_shell_command.
  • client.schematic, client.layout, client.library, client.symbol — the design targets.
  • client.maestro, client.sos — the Maestro and SOS targets.
  • client.dialogs, client.requests — the dialog and request targets.
  • spectre — the Spectre target.

Arguments are positional in args and named in kwargs. Rich values use explicit markers: {"$type":"path","value":"/projects/example/x.il"} for a remote path and {"$type":"bytes","data":"<base64>"} for bytes. Dataclass results such as VirtuosoResult and SimulationResult are converted to JSON. timeoutSec bounds the bridge-side operation.

SKILL through the APIJSON
{"action": "call",
 "target": "client",
 "method": "execute_skill",
 "args": ["1+1"],
 "description": "Check the daemon answers",
 "timeoutSec": 60}

A call can carry an optional one-line description, used as the tool-card label. Every call renders as the same expandable code card as a script run. An execute_skill call shows its SKILL source as code. Another call shows its arguments. Both carry the dsh-virtuoso-bridge badge.

Script tool

virtuoso_bridge_script runs Python in a new venv process, never in the sidecar. A bad batch therefore cannot break the connection. The script gets connect(), emit() and a result convention:

Script contractPYTHON
import virtuoso_bridge as vb
client = connect()          # reuse the running tunnel/daemon
emit({"progress": 0.5})     # structured progress
result = {"done": True}     # persisted as result.json

A run takes exactly one source: inline code, or path to a Python file. A relative path resolves against the Session working directory, so it names the file the ordinary file tools just wrote. Each run copies the current file content into its own job directory, so an edit applies to the next run. Jobs are independent; there is no fixed scratch script.

ActionWhat it does
runStart a job and return Running with its id when it is still in flight.
statusReturn the full job snapshot, including incremental stdout and stderr.
listList recent jobs.
cancelCancel a job.

Jobs have ids, status, incremental stdout and stderr, a hard timeout and cancellation. A job started in one conversation can be polled from another. The plugin indexes the last 40 job directories when it starts.

Every call needs a short one-line description, used as the tool-call label and history title. A successful run returns Success and the result. A running job returns Running and its id. A failure returns the error and the id. Internal paths, code previews, status records and auto-connect fields are not exposed.

Fold the probes

One larger script beats several small runs. Fold the measurements and edits you need into one body, and print what you measured. When you will revisit the work, keep it in a workspace file and pass path. An edit then applies to the next run without resending the body. Inline code is simpler for a one-off probe.

Reusable fileJSON
{"action": "run", "path": "batch.py",
 "description": "Measure open schematic windows",
 "timeoutSec": 600}

Setup tool

virtuoso_bridge_setup owns the isolated venv, its source and its caches. status and preflight return only the facts you need to choose the next step. The full install log, source details and storage list stay on the configuration page.

ActionWhat it does
statusReport installed state, source mode, venv, SSH backends and cache directory.
preflightReport supported backends and the extra definition before an install.
installCreate or repair the venv and install the selected source.
updateReinstall from the current source, and fetch a git source again.
diagnoseReturn the explicit plugin-debugging report, including Host self-checks.
configurePersist runtime defaults such as the Python executable and the cache directory.
set_sourceSelect bundled source, a local development repo or a git repository at a ref.
cachesList cache items with paths, sizes and file counts.
clear_cacheClear one cache: pip, sources, jobs, results or logs.

Install brings the SSH extra (paramiko plus PySocks) by default and verifies import virtuoso_bridge from the plugin venv. If OpenSSH is missing from PATH, install stops and returns a confirmation request. Retry with confirm: true to use the Paramiko backend only.

Install without OpenSSHJSON
{"action": "install", "confirm": true}

CIW diagnostics

Read the CIW block before you guess why a call did nothing. A virtuoso_bridge_api call and a settled virtuoso_bridge_script job append a compact CIW block when the CIW printed something during the call:

Attached CIW blockTEXT
--- CIW: 1 warning, 1 error, 1 output line (41 other lines) ---
*WARNING* (DB-270212): dbOpenCellViewByType: ...
CDF: An error occurred when evaluating callback.

The header counts warnings, errors and output lines, and notes the rest of the shared transcript. Capture is best effort. A local Windows Virtuoso, a missing /proc or a busy lane can skip it, and an absent block does not mean the CIW was quiet. Warnings are flushed from the SKILL warning port, and the block is read from the session CDS.log. Its writer batches text, so a line can arrive one call late. A failed call and a settled script job wait briefly before reading.

A captured line can come from the human or from another tool. Treat the block as CIW output, not as proof about the result it is attached to. Capture never fails a call; uncheck Report CIW warnings/errors with results (ciwReport) on the configuration page to turn it off. To read the CIW explicitly when the block is missing, use the workflow recipe.

Installed skills

Setup installs the upstream documentation — skills/, README.md and AGENTS.md — into:

Instructions directoryTEXT
<dataDir>/instructions/

The plugin registers a virtuoso-bridge skill in the DSH skill catalog with that directory as its resource base, and lists every installed SKILL.md. The system prompt gives the same absolute path and tells the agent to read the matching skill or reference before issuing bridge commands. Agents must not guess virtuoso-bridge CLI flags. For connections, deployment, automatic sessions and instance selection, read skills/virtuoso/references/connection.md.

Reinstall or update the bridge to refresh the installed documentation. Setup also installs references/agent-workflows.md, a short wrapper guide over the existing VBL APIs.

Batching work

Every extra call is a round trip. Use a few large calls instead of many small ones:

  • Fold probes into one script. Put the reads, edits and checks into one body, and print what you measured.
  • Describe once. Read the target's signatures, then call it. Do not rediscover the same method at every step.
  • Prefer a script to repeated calls. One job that loops over the client beats ten separate calls.
  • Let big answers become files. An oversized answer is written under <cache dir>/results/. Grep the path instead of asking again.
Read state before acting

A runtime operation can be in flight. status with waitMs waits for the start to settle, so the next call does not race the state it is about to use.