# ViraStack Agent Bridge

An experimental, agent-neutral MCP/CLI adapter for **Cadence ViraStack in Virtuoso IC26.1**.
Every design action is delegated to the native ViraStack agent and its permission system.

[中文说明](README.zh-CN.md)

```mermaid
flowchart LR
  A[Any agent] --> B[MCP or CLI]
  B --> C[SSH worker]
  C --> D[Native ViraStack task manager]
  D --> E[Virtuoso tools]
  D <--> F[JedAI and your chosen model service]
```

The bridge reuses the official MCP Python SDK and SkillBridge transport. ViraStack owns
task scheduling, tool execution, confirmations, results, and cancellation. Its existing
native task IDs are wrapped in tickets that detect stale or mismatched sessions.

## Requirements

- A licensed, running ViraStack session with a working model service.
- Linux Python 3.9+ in the Virtuoso host for the native worker.
- Python 3.10+ in the agent host for MCP; an SSH client for remote operation.

Cadence software, model credentials, licenses, PDKs and design data are supplied by the
user's environment. This project is an independent integration; IC26.1's replay interface
is version-sensitive. See [validation](docs/validation.md) for the exact tested scope.

## Install the native worker

On the Virtuoso host, install this source checkout into a dedicated environment:

```sh
python3 -m venv ~/.venvs/virastack-bridge
~/.venvs/virastack-bridge/bin/pip install '.[native]'
~/.venvs/virastack-bridge/bin/python -c \
  'from importlib.resources import files; print(files("skillbridge") / "server/python_server.il")'
```

Load the printed file in the intended Virtuoso session, then start its transport:

```lisp
load("/absolute/path/skillbridge/server/python_server.il")
pyStartServer(?id "virastack" ?python "/home/you/.venvs/virastack-bridge/bin/python")
```

Reuse an existing SkillBridge server and its workspace ID when one is already running.
Connect ViraStack to your model service and keep the intended chat open.

## Install the agent front end

```sh
python -m pip install '.[mcp]'
```

Configure the SSH host alias through your normal SSH setup, then set:

```sh
export VIRASTACK_BRIDGE_SSH_TARGET=eda-server
export VIRASTACK_BRIDGE_REMOTE_PYTHON=/home/you/.venvs/virastack-bridge/bin/python
export VIRASTACK_BRIDGE_WORKSPACE=virastack
```

`VIRASTACK_BRIDGE_SSH_IDENTITY` and `VIRASTACK_BRIDGE_KNOWN_HOSTS` are optional file paths.
Host-key checking and batch authentication are enforced. For a front end running directly
on the Linux Virtuoso host, omit `VIRASTACK_BRIDGE_SSH_TARGET`.

## Use from any agent

An MCP client's server configuration can launch:

```json
{
  "mcpServers": {
    "virastack": {
      "command": "virastack-agent-bridge",
      "args": ["mcp"],
      "env": {
        "VIRASTACK_BRIDGE_SSH_TARGET": "eda-server",
        "VIRASTACK_BRIDGE_REMOTE_PYTHON": "/home/you/.venvs/virastack-bridge/bin/python",
        "VIRASTACK_BRIDGE_WORKSPACE": "virastack"
      }
    }
  }
}
```

Tools: `virastack_status`, `virastack_sessions`, `virastack_submit`,
`virastack_job`, `virastack_cancel`, and `virastack_reply`.

Select a chat explicitly. Submit a request, retain its ticket, and poll `virastack_job`.
A single foreground request is submitted at a time per Virtuoso application.
A submission acknowledgement does not mean the task completed. Read the native result
and evidence to assess whether the requested design goal was achieved. Native pending
questions are handled through `virastack_reply`; permissions are not automatically granted.

Agents that use shell tools can use the same interface:

```sh
virastack-agent-bridge sessions
virastack-agent-bridge submit --chat 0 --prompt \
  'Use the native Virtuoso tool to read getVersion(). Do not change designs or run simulations.'
virastack-agent-bridge job TICKET_FROM_SUBMIT
```

For larger or private prompts, use `--prompt-file file.txt` or `--prompt-file -`.
After a client timeout, inspect `sessions` for `latest_ticket` before resubmitting.

## Model backends

The external agent and ViraStack's model backend are independent. Configure the model
service in JedAI/ViraStack. The adapter contains no Codex-specific authentication code.
The current live native-agent validation used `gpt-6.1-sol`; model selection affects
delegation and tool-use reliability.

For personal Codex login reuse, a separately installed compatible proxy such as
[codex-openai-proxy](https://github.com/CIVITAS-John/codex-app-server-to-proxy) can serve
as the model backend through a loopback-only SSH tunnel. Follow that project's pinned
runtime and authentication instructions. Keep account credentials on their original host.

## Development

```sh
python -m unittest discover -s tests -v
```

Protocol tests use fakes; live validation is opt-in and uses a real licensed server.
See [third-party components](THIRD_PARTY.md) and [validation](docs/validation.md).