eda-bridge-runtime 0.1.0a5__tar.gz

eda_bridge_runtime-0.1.0a5/.agents/plugins/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "eda-bridge-runtime",
+  "interface": {
+    "displayName": "Eda Bridge Runtime"
+  },
+  "plugins": [
+    {
+      "name": "eda-bridge-runtime",
+      "source": {
+        "source": "local",
+        "path": "./plugins/eda-bridge-runtime"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_USE"
+      },
+      "category": "Developer Tools"
+    }
+  ]
+}

eda_bridge_runtime-0.1.0a5/.github/workflows/publish.yml

@@ -0,0 +1,81 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.13"
+      - name: Verify tag matches package version
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: |
+          python - <<'PY'
+          import pathlib
+          import tomllib
+          import os
+
+          version = tomllib.loads(pathlib.Path("pyproject.toml").read_text())["project"]["version"]
+          tag_version = os.environ["RELEASE_TAG"].removeprefix("v")
+          if version != tag_version:
+              raise SystemExit(f"tag {tag_version!r} does not match package {version!r}")
+          PY
+      - run: python -m pip install --upgrade build twine
+      - run: python -m pip install -e ".[dev]"
+      - run: pytest
+      - run: ruff check .
+      - run: python -m build
+      - run: python -m twine check dist/*
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.0
+        with:
+          name: python-package-distributions
+          path: dist/
+          if-no-files-found: error
+          retention-days: 7
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/eda-bridge-runtime
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.0
+        with:
+          name: python-package-distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
+
+  verify:
+    needs: publish
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.13"
+      - name: Install the exact published version
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: |
+          version="${RELEASE_TAG#v}"
+          for attempt in 1 2 3 4 5 6; do
+            if python -m pip install --no-cache-dir "eda-bridge-runtime==$version"; then
+              python -c "import eda_bridge_runtime; assert eda_bridge_runtime.__version__ == '$version'"
+              eda-runtime --help
+              exit 0
+            fi
+            sleep 10
+          done
+          exit 1

eda_bridge_runtime-0.1.0a5/.gitignore

@@ -0,0 +1,15 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+dist/
+build/
+.coverage
+htmlcov/
+.codex_tmp/
+*.sqlite3
+*.sqlite3-shm
+*.sqlite3-wal
+

eda_bridge_runtime-0.1.0a5/AGENTS.md

@@ -0,0 +1,11 @@
+# Agent working agreement
+
+- Treat this as a public repository. Never add customer data, credentials,
+  private hostnames, private paths, or proprietary EDA models.
+- Preserve the agent-neutral and vendor-neutral boundary.
+- Every operation initiated by an agent must include a concise `purpose`.
+- Prefer typed capabilities over arbitrary script execution.
+- Keep local and SSH behavior conformant through shared tests.
+- Do not claim success until durable state or a fresh observation proves it.
+- Do not publish or create releases without explicit owner authorization.
+

eda_bridge_runtime-0.1.0a5/CONTRIBUTING.md

@@ -0,0 +1,6 @@
+# Contributing
+
+Keep the core agent-neutral and vendor-neutral. New EDA behavior belongs in an
+adapter package. Protocol changes require schema updates, compatibility tests,
+and a short migration note. Tests must use synthetic or sanitized scratch data.
+

eda_bridge_runtime-0.1.0a5/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Pengfei Li
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

eda_bridge_runtime-0.1.0a5/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.5
+Name: eda-bridge-runtime
+Version: 0.1.0a5
+Summary: Agent-neutral execution runtime for local and remote EDA bridges
+Author: Pengfei Li
+License: MIT License
+        
+        Copyright (c) 2026 Pengfei Li
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# EDA Bridge Runtime
+
+<img src="plugins/eda-bridge-runtime/assets/logo.png" width="180" alt="EDA Bridge Runtime logo">
+
+`eda-bridge-runtime` is an agent-neutral execution layer for EDA automation.
+It gives local and SSH-driven bridges the same request envelope, durable job
+semantics, context handoff, timing evidence, and append-only execution ledger.
+
+The runtime is intentionally not an EDA bridge and not an AI harness. Vendor
+bridges keep their native API knowledge. Agents state a short purpose; the
+runtime records what was requested, what actually ran, how long each phase
+took, and what result or artifact was produced.
+
+## Design promises
+
+- Local and SSH execution use one protocol and one evidence model.
+- Every agent-originated operation carries a concise `purpose`.
+- Actor metadata is collected automatically where possible and records its
+  provenance; missing metadata never blocks engineering work.
+- Mutating requests are idempotent and auditable.
+- Disconnection does not imply that a long EDA job failed.
+- Context tokens contain locators and fingerprints, never credentials.
+- EDA-specific behavior lives in adapters, not in the runtime core.
+
+## Current alpha
+
+`0.1.0a5` adds agent-host lifecycle auditing without changing tool permissions. Codex hooks record
+session, turn, model, permission mode, tool-call identity, concise purpose, and a content hash before
+an EDA Runtime call, then link the completed call to its actual Run. The audit is append-only,
+hash-chained, and stores neither raw operation payloads nor chat transcripts.
+
+`0.1.0a4` adds rich bounded Context snapshots, stable origin routing, direct
+one-submit execution, and automatic origin binding during connection setup.
+Vendor Skills can declare the Runtime MCP directly, so users select one
+task-facing Skill rather than manually composing infrastructure Skills.
+
+```powershell
+python -m pip install "eda-bridge-runtime==0.1.0a5"
+eda-runtime doctor
+```
+
+For repository development, create a virtual environment and install `.[dev]`
+instead. Public releases are built once on a clean GitHub runner, published
+through PyPI Trusted Publishing, and installed back from PyPI before acceptance.
+
+See [Architecture](docs/ARCHITECTURE.md) and the
+[protocol schema](docs/schemas/request-v1.schema.json). Host placement is
+defined by the [agent-client, eda-worker, and combined deployment roles](docs/DEPLOYMENT_ROLES.md).
+
+The proposed lightweight Pi Agent pilot is described in
+[Pi Agent pilot](docs/PI_AGENT_PILOT.md). It reuses the same Runtime boundary instead of adding a
+second SSH or EDA-control path.
+
+The repository also includes a minimal [MCP and Codex plugin](docs/MCP_AND_CODEX.md). It resolves
+named local/SSH connections without asking the agent to assemble transport commands on each call.
+Sanitized real-host evidence is recorded in [acceptance results](docs/ACCEPTANCE.md).

eda_bridge_runtime-0.1.0a5/README.md

@@ -0,0 +1,56 @@
+# EDA Bridge Runtime
+
+<img src="plugins/eda-bridge-runtime/assets/logo.png" width="180" alt="EDA Bridge Runtime logo">
+
+`eda-bridge-runtime` is an agent-neutral execution layer for EDA automation.
+It gives local and SSH-driven bridges the same request envelope, durable job
+semantics, context handoff, timing evidence, and append-only execution ledger.
+
+The runtime is intentionally not an EDA bridge and not an AI harness. Vendor
+bridges keep their native API knowledge. Agents state a short purpose; the
+runtime records what was requested, what actually ran, how long each phase
+took, and what result or artifact was produced.
+
+## Design promises
+
+- Local and SSH execution use one protocol and one evidence model.
+- Every agent-originated operation carries a concise `purpose`.
+- Actor metadata is collected automatically where possible and records its
+  provenance; missing metadata never blocks engineering work.
+- Mutating requests are idempotent and auditable.
+- Disconnection does not imply that a long EDA job failed.
+- Context tokens contain locators and fingerprints, never credentials.
+- EDA-specific behavior lives in adapters, not in the runtime core.
+
+## Current alpha
+
+`0.1.0a5` adds agent-host lifecycle auditing without changing tool permissions. Codex hooks record
+session, turn, model, permission mode, tool-call identity, concise purpose, and a content hash before
+an EDA Runtime call, then link the completed call to its actual Run. The audit is append-only,
+hash-chained, and stores neither raw operation payloads nor chat transcripts.
+
+`0.1.0a4` adds rich bounded Context snapshots, stable origin routing, direct
+one-submit execution, and automatic origin binding during connection setup.
+Vendor Skills can declare the Runtime MCP directly, so users select one
+task-facing Skill rather than manually composing infrastructure Skills.
+
+```powershell
+python -m pip install "eda-bridge-runtime==0.1.0a5"
+eda-runtime doctor
+```
+
+For repository development, create a virtual environment and install `.[dev]`
+instead. Public releases are built once on a clean GitHub runner, published
+through PyPI Trusted Publishing, and installed back from PyPI before acceptance.
+
+See [Architecture](docs/ARCHITECTURE.md) and the
+[protocol schema](docs/schemas/request-v1.schema.json). Host placement is
+defined by the [agent-client, eda-worker, and combined deployment roles](docs/DEPLOYMENT_ROLES.md).
+
+The proposed lightweight Pi Agent pilot is described in
+[Pi Agent pilot](docs/PI_AGENT_PILOT.md). It reuses the same Runtime boundary instead of adding a
+second SSH or EDA-control path.
+
+The repository also includes a minimal [MCP and Codex plugin](docs/MCP_AND_CODEX.md). It resolves
+named local/SSH connections without asking the agent to assemble transport commands on each call.
+Sanitized real-host evidence is recorded in [acceptance results](docs/ACCEPTANCE.md).

eda_bridge_runtime-0.1.0a5/SECURITY.md

@@ -0,0 +1,11 @@
+# Security
+
+Do not place EDA license strings, SSH private keys, bridge authentication
+tokens, customer designs, or customer paths in requests or ledger metadata.
+The runtime redacts common secret-shaped keys before persistence, but callers
+remain responsible for using artifact references instead of embedding private
+payloads.
+
+Report security issues privately to the repository owner. Do not open a public
+issue containing credentials, proprietary design data, or host inventories.
+

eda_bridge_runtime-0.1.0a5/docs/ACCEPTANCE.md

@@ -0,0 +1,74 @@
+# Sanitized acceptance evidence
+
+Acceptance used a remote Linux EDA host over one persistent SSH transport. No customer project,
+credentials, host address, or task-specific geometry is included here.
+
+## 2026-08-29 Codex lifecycle-audit acceptance
+
+- A freshly installed `0.1.0-alpha.5` plugin loaded its bundled
+  `hooks/hooks.json` in a new Codex CLI session and called `eda.connections.list` exactly once.
+  This non-interactive acceptance used Codex's explicit hook-trust bypass after the installed Hook
+  file was inspected; normal interactive use presents the standard one-time trust review.
+- The pre- and post-tool hooks produced two consecutive, hash-linked audit events. They observed
+  the Codex model, session, turn, tool-call identity, permission mode, and concise declared purpose.
+- The events stored a SHA-256 fingerprint instead of the raw MCP arguments. No chat transcript,
+  customer data, connection details, or credentials were copied into the Agent audit.
+- The diagnostic connection-list call correctly recorded `execution.linked=false` because it does
+  not create an EDA Run. Runtime operation tests cover completion linkage to the returned Run view.
+- The two hook records were 609 ms apart, including the MCP call itself. Hook handlers do not
+  rewrite the pending call or return an allow decision, so telemetry cannot bypass tool approval.
+
+## 2026-08-28 convergence acceptance
+
+- The installed Agent-side MCP exposed six typed tools, including `eda.capabilities`.
+- Capability discovery through the registered SSH connections took 438 ms for ADS and 422 ms for
+  AnsysEM on the first measurement. Both adapters reported `execution_host_role=eda-worker`; ADS
+  reported a synchronous Run model and AnsysEM a durable Run model.
+- ADS 2026 Update 2.1 created one disposable empty workspace on virtual display 4 in 1.55 seconds.
+  A repeated call with the same idempotency key returned the original Run in 265 ms and did not
+  recreate the workspace.
+- AEDT 2026.1 / PyAEDT 1.4.0 created, saved, closed, and fresh-reopened one disposable empty HFSS
+  3D Layout project on virtual display 4. Submission returned in 453 ms and the durable Run reached
+  `passed` after 42.4 seconds. Status observations normally took 0--16 ms over the reused transport.
+- Repeating the AnsysEM submission returned the same `job_id` and original `run_id`; later status
+  and event calls observed that Run without replaying it.
+- The first AnsysEM attempt exposed a missing propagation of the connection-level runtime profile
+  into detached workers. The Bridge now inherits this profile automatically; a regression test and
+  the successful real-host rerun cover the failure path.
+
+## 2026-08-28 Context v2 and dual-role acceptance
+
+- Both vendor Bridges emitted bounded `EDA_CONTEXT:v2` tokens containing a stable origin, session
+  state, target summary, capability digest, and freshness state. Runtime selected the correct
+  registered connection from the origin without a connection hint; legacy v1 decoding remains
+  covered by tests.
+- One ADS documentation query completed with a single `eda.submit` over the SSH route in 529 ms.
+  One AnsysEM documentation query completed over the production SSH route in 860 ms. Neither path
+  launched the EDA or required separate context-resolution and capability calls.
+- The same Runtime and AnsysEM adapter completed a documentation-status request through a local
+  connection in 72 ms when the EDA worker also acted as the Agent host. Only the connection record
+  differed between the local and SSH paths.
+- Acceptance caught that an SSH child initially inherited the host's default virtual display even
+  though the captured Context named another display. The production connection commands now bind
+  the display before launching either Bridge; the ledgers then observed the required display for
+  both adapters.
+- Connection setup probed each Bridge once and persisted its origin. Subsequent Context-driven
+  requests did not spend an extra round trip rediscovering the target.
+
+## Evidence boundary
+
+- Both append-only ledgers verified their hash chains after the real operations.
+- Recorded facts include the concise declared purpose, MCP client and harness identity, observed
+  host/display/runtime facts, adapter events, and terminal result. Metadata unavailable from the
+  client remains explicitly `unknown` with provenance instead of being guessed.
+- Scratch output completeness was checked, then the disposable artifacts were removed. No customer
+  model was opened, no solve was launched, and no GUI automation was used.
+
+## Package and failure-path checks
+
+- Unit tests cover hash-chain integrity, source identity, handshake mismatch, malformed-frame
+  isolation, idempotency, leases, durable jobs, orphan detection, connection ambiguity, legacy and
+  stateless MCP discovery, context routing, and no-replay connection failure.
+- Runtime, ADS adapter, and AnsysEM adapter tests pass; lint passes for Runtime, AnsysEM, and all
+  modified ADS files. The wider ADS repository retains unrelated pre-existing lint debt.
+- The Codex plugin manifest and bundled Skill pass their validators.

eda_bridge_runtime-0.1.0a5/docs/ARCHITECTURE.md

@@ -0,0 +1,63 @@
+# Architecture
+
+## One execution path
+
+An agent, CLI, MCP server, or EDA UI creates a versioned request envelope. The
+runtime reads an explicit `EDA_CONTEXT` snapshot or a deterministic registered
+binding, opens either a local or SSH transport, and submits the request to an
+EDA adapter. A v2 Context adds bounded origin, session, target, selection,
+capability, and freshness facts; v1 remains accepted. When the selected Skill
+already establishes a typed operation, `eda.submit` performs routing, freshness
+validation, and execution in one client call.
+
+All paths emit the same event model into one logical execution ledger:
+
+`client -> runtime -> transport -> adapter -> vendor bridge -> EDA`
+
+The ledger keeps declared intent separate from observed execution. Physical
+client and server ledger segments may live on different hosts; `request_id`,
+`run_id`, `trace_id`, sequence numbers, and event hashes make them mergeable.
+
+## Three logical responsibility domains
+
+The system has three logical responsibility domains. Skill, MCP, transport,
+and SSH are interfaces or internal modules, not additional product layers.
+
+| Domain | Owns | Does not own |
+|---|---|---|
+| User and Agent | Intent, engineering judgment, concise purpose | Durable execution state |
+| Runtime kernel | Identity enrichment, facts, routing, transport, leases, jobs, Run projection | EDA semantics |
+| Vendor adapter and bridge | Typed EDA capabilities, native API calls, EDA lifecycle, result normalization | Agent policy or cross-EDA governance |
+
+The physical modules remain separable for testing. MCP and CLI are stateless
+frontends to the Runtime kernel; local and SSH are interchangeable transports;
+Skills are routing policy; vendor adapters preserve real EDA differences.
+See [Deployment roles](DEPLOYMENT_ROLES.md) for host placement.
+
+## Reliability model
+
+Delivery is at-least-once. Mutating operations therefore require an
+`idempotency_key`. Durable jobs persist state before execution, expose an event
+cursor, and allow clients to reconnect without restarting the EDA operation.
+Resource leases carry monotonically increasing fencing tokens so a stale worker
+cannot claim current ownership.
+
+Synchronous responses and durable jobs retain their existing wire formats. The
+Runtime adds a compact `eda-runtime.run-view/v1` projection so clients observe
+the same run identity, state, terminal flag, job identity, and path-free
+evidence references without forcing ADS and AnsysEM to share one execution
+implementation.
+
+## Escape lanes
+
+The preferred path is a typed adapter capability. If unavailable, callers may
+use a verified native API, then a bounded script, then bounded GUI assistance,
+then a manual external action. Adapters advertise which lanes exist. Every
+non-typed lane must be explicit in the request and ledger.
+
+## Privacy and retention
+
+Structured ledger records are retained until user cleanup. Raw vendor/debug
+logs are artifacts with a default seven-day retention policy. Context tokens
+contain no secrets. Structured values are redacted recursively before being
+written.

eda_bridge_runtime-0.1.0a5/docs/DEPLOYMENT_ROLES.md

@@ -0,0 +1,63 @@
+# Deployment roles
+
+The Runtime uses two independent host roles. They may be installed on separate
+machines or combined on one machine; the execution contract does not change.
+
+## Agent client
+
+The agent host owns the user-facing Skill, MCP server, connection registry,
+context resolution, and transport reuse. It does not need the EDA application
+or a vendor bridge installed locally when the selected connection is SSH.
+
+Required components:
+
+- `eda-runtime mcp serve` and the Runtime Codex plugin;
+- `~/.eda-bridge-runtime/connections.json` or an explicitly selected registry;
+- the thin Runtime routing Skill;
+- platform SSH configuration when an EDA worker is remote.
+
+## EDA worker
+
+The EDA host owns the vendor adapter service, bridge, EDA add-on or add-in, EDA
+process, durable worker state, and vendor evidence. It does not need Agent
+Skills or the Runtime Codex plugin unless an Agent also runs on that host.
+
+Required components:
+
+- the shared Runtime protocol library;
+- one vendor bridge and its Runtime adapter service;
+- the intended EDA installation, runtime profile, display, and license;
+- host-side job, ledger, and artifact state used by that bridge.
+
+## Combined host
+
+A combined host installs both roles and selects a `local` Runtime connection.
+It still traverses MCP, Runtime, and the vendor adapter; only SSH is removed.
+This preserves purpose, actor, idempotency, Run, and evidence behavior between
+local and remote deployments.
+
+```text
+Agent host                                      EDA host
+-----------                                     --------
+Agent -> Skill -> MCP -> Runtime client         Runtime adapter service
+                         |                      -> vendor bridge
+                         +-- local or SSH ------> -> EDA add-on/API -> EDA
+```
+
+Skills are Agent instructions, not remote execution services. Documentation
+query backends and licensed corpora may live on either host, but their
+user-facing Skill belongs wherever the Agent runs.
+
+## Installation-state proof
+
+An Agent capability is usable only when four states agree:
+
+1. repository source;
+2. installed Python package;
+3. installed plugin and Skill cache;
+4. tools exposed to a freshly started Agent session.
+
+An EDA worker is proven separately by its installed bridge version, adapter
+capabilities, EDA/profile identity, and a bounded real-host acceptance check.
+Static Skills found on an EDA-only host do not participate in a remote Agent's
+route and must not be treated as worker dependencies.

eda_bridge_runtime-0.1.0a5/docs/MCP_AND_CODEX.md

@@ -0,0 +1,79 @@
+# MCP and Codex plugin
+
+The bundled plugin is a thin discovery layer. It starts `eda-runtime mcp serve`, while the Runtime
+keeps transport, idempotency, durable jobs, and the execution ledger independent of Codex.
+The plugin and Skill belong on the Agent host. A remote EDA host needs only the
+shared Runtime protocol plus its vendor bridge and adapter service unless an
+Agent also runs there.
+
+The plugin also installs `PreToolUse` and `PostToolUse` hooks scoped only to its own MCP tools.
+They write an Agent-host append-only audit that records the Codex session, turn, active model,
+permission mode, tool-call identity, concise purpose, and a hash of the arguments. Completion links
+that identity to the returned Runtime Run. Hooks do not rewrite inputs, approve tools, parse the
+chat transcript, or store raw operation payloads. Inspect the bounded recent view with
+`eda-runtime audit list`.
+
+Codex asks for one-time trust when a new or changed plugin Hook is first used. Review and approve
+the two bundled audit commands; routine calls need no extra Agent prompt after that. Automated
+acceptance may use Codex's explicit hook-trust bypass only after validating the installed Hook file.
+
+The stdio server supports both the legacy MCP initialization era through `2025-11-25` and the
+stateless `2026-07-28` discovery era. It exposes six tools:
+
+- `eda.context.resolve`
+- `eda.connections.list`
+- `eda.capabilities`
+- `eda.submit`
+- `eda.job.status`
+- `eda.job.events`
+
+Operation, status, and event calls include an additive compact `run` object.
+It projects synchronous responses and durable jobs into one observation shape
+and lists content-addressed evidence metadata without exposing artifact paths.
+
+For a greenfield task, use the create operation established by the selected vendor Skill; discover
+capabilities only when that operation is not known. ADS and AnsysEM intentionally keep different
+creation schemas; both return a bounded, reusable `EDA_CONTEXT` without exposing credentials or
+large private artifacts.
+
+When a selected Skill and Context establish the operation, call `eda.submit` directly. Separate
+`eda.context.resolve` and `eda.capabilities` calls are diagnostic and discovery tools, not mandatory
+preflight. The adapter still validates the Context generation and target before execution.
+
+The tools never accept a raw local or SSH launch command. They select a previously registered
+connection by `connection_id`, by a stable `origin_id` in `EDA_CONTEXT`, or by an unambiguous EDA
+match. Each Agent host may map the same origin to a different local or SSH route.
+
+## One-time connection registration
+
+Installation or administration code registers the connection once. Engineers normally copy
+context from the EDA UI and do not maintain this file themselves.
+
+```console
+eda-runtime connection set --eda ansys-electronics-desktop --kind ssh \
+  --host eda-host --ssh-option=-o --ssh-option=BatchMode=yes \
+  ansys-lab /opt/eda/bin/ansysem-agent runtime serve
+
+eda-runtime connection set --eda keysight-ads --kind local \
+  ads-local ads-agent runtime serve
+```
+
+Registration probes the adapter once and stores its stable `origin_id`; engineers do not create or
+maintain that identifier. `--origin-id` is an administrative override and `--no-origin-probe`
+exists only for repair or legacy adapters.
+
+The default registry is `~/.eda-bridge-runtime/connections.json`. Set `EDA_RUNTIME_HOME` to move
+the whole Runtime control directory. Do not store credentials in the registry; SSH authentication
+remains in the platform SSH configuration.
+
+## Plugin source
+
+The repository plugin lives at `plugins/eda-bridge-runtime`. Install the Python package first so
+that `eda-runtime` is on the host path, then install the repository marketplace and plugin:
+
+```console
+codex plugin marketplace add cottman99/eda-bridge-runtime --ref main
+codex plugin add eda-bridge-runtime@eda-bridge-runtime
+```
+
+Restart the Codex client after first installation so its Skill and MCP server are loaded together.