@vention/vention-skills 0.10.14 → 0.10.15

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "vention",
-  "version": "0.10.14",
+  "version": "0.10.15",
   "description": "Vention skills for coding agents: write MachineLogic applications, build machine designs, and diagnose deployed machines.",
   "author": {
     "name": "Vention"

package/README.md

@@ -1,6 +1,6 @@
 # Vention skills
 
-Version 0.10.14. Skills for coding agents that work with Vention machines, packaged as one plugin, `vention`, in the `vention-skills` marketplace.
+Version 0.10.15. Skills for coding agents that work with Vention machines, packaged as one plugin, `vention`, in the `vention-skills` marketplace.
 
 | Skill                       | What it does                                                                                                                         |
 | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vention/vention-skills",
-  "version": "0.10.14",
+  "version": "0.10.15",
   "description": "Vention skills for coding agents: write MachineLogic applications, build machine designs, and diagnose deployed machines.",
   "license": "MIT",
   "type": "module",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "vention",
-  "version": "0.10.14",
+  "version": "0.10.15",
   "description": "Vention skills for coding agents: write MachineLogic applications, build machine designs, and diagnose deployed machines.",
   "author": {
     "name": "Vention"

package/skills/vention-design/SKILL.md

@@ -3,7 +3,7 @@ name: vention-design
 description: Create, build and edit Vention machine designs and design graphs for agentic layout. Use when the user wants to start a new design, lay out an automation cell, add or reposition components in a Vention design, generate a machine layout from a description, add or place a floor plan image under a design, list a design's versions, or inspect an existing design graph. Trigger on MachineBuilder designs, design graphs, assembly graphs, extrusions, actuators, robot mounting, cell footprints, floor plans, or a machine-builder URL.
 license: MIT
 metadata:
-  version: "0.10.14"
+  version: "0.10.15"
   author: Vention
 ---
 

package/skills/vention-machine-logic/SKILL.md

@@ -3,7 +3,7 @@ name: vention-machine-logic
 description: Write, edit, validate, and deploy MachineLogic Python applications for Vention machines with the machine-logic-sdk and the Vention CLI. Load it before writing or changing any Python that talks to a Vention machine, however short, since device names and version-specific SDK calls come from here. Use to program a Vention machine or MachineMotion controller, drive actuators, conveyors, robots, pneumatics, or digital I/O, change an existing application, build a state machine, debug from logs, or pull, push, or link with the Vention CLI (vention or vn). Trigger on MachineLogic, machine-logic-sdk, MachineMotion, MachineBuilder applications, the Vention CLI, or a directory holding .machine-code-app-directory-info.json. Printing what the machine or robot holds now (positions, taught targets, calibration, I/O) is a program: files on disk hold only as-designed values. Not for explaining an existing machine or its configuration in words when no program is asked for, nor for Python that never touches the machine.
 license: MIT
 metadata:
-  version: "0.10.14"
+  version: "0.10.15"
   machine-logic-sdk: ">=3.0,<4"
   author: Vention
 ---
@@ -245,7 +245,7 @@ Each example is a standalone `main.py` whose module docstring names the device n
 4. If `uv` is missing or the install fails, tell the user the code is unvalidated. Never report a check you could not run as passed.
 5. `vention push`, then run the application on the digital twin from MachineBuilder before any hardware run. One or two full cycles prove the cycle; each extra one costs a cycle time and shows nothing the first two did not. Run them at 100 % of the speed setting, chosen for that run: nothing on the twin can be hurt.
 6. Read the output with `vention logs` once the run ends, rather than following it while the cycles play. `vention logs` prints only the most recent lines, so a count of matching lines can stop rising before the run ends. Print each cycle's measured time. When the cycle time is unknown, sleep once for one cycle's estimate, read `vention logs` once for the measured time, then sleep once for the cycles left: a rounded-up guess for the whole run wastes the difference. Before that first sleep, read `vention logs` once a few seconds after starting the run, to see that the first cycle began: a run stuck before its first move would otherwise cost the whole sleep. Print a line before every call that can block for long, such as a home or a long move, not only after it, so a log that stops shows which call it stopped in. Never loop over `vention logs` waiting for a line to appear, and never end your turn while a background wait is running. MachineLogic failures name the device and the reason; read the log before proposing a change.
-7. Check a motion from the log, not by watching the twin: `print` the robot's joint angles or the axis position at each step, then compare them with what the step should reach. For a repeated or oscillating motion, such as a wave, print the joint angles at each end of the swing, so the log alone shows how far it moved and which joints moved.
+7. Check a motion from the log, not by watching the twin: `print` the robot's joint angles (`angles, _timestamp = robot.state.joint_angles_data`) or the axis position at each step, then compare them with what the step should reach. For a repeated or oscillating motion, such as a wave, print the joint angles at each end of the swing, so the log alone shows how far it moved and which joints moved.
 8. On the digital twin, `home()` can hang: it does not return, even past its timeout, because the SDK keeps retrying the request. The twin also reports an axis's end sensors as off at every position, so their state cannot tell you where the axis is. Never delete the homing to get past a hang: the hardware needs it. Stop the run, tell the user the home did not finish on the twin, and ask whether to skip the home on the twin only.
 9. Pressing the emergency stop on the digital twin's pendant does nothing, so skip that test there. Tell the user the e-stop path is untested until the first run on the real cell.
 10. Show the user the diff before pushing over an application they did not write in this session.
@@ -257,6 +257,8 @@ The controller keeps its own scene. Positions re-taught on the pendant and the c
 - Deploy over the LAN from the application's Deploy menu in MachineBuilder with only the application ticked. "Design-level Scene Assets" replaces the controller's positions with the design's, including every one re-taught on the pendant, and "Configuration" replaces its configuration.
 - When the application needs a position the controller lacks, ask the user to teach it on the pendant under the same name it has on the design.
 - Deploying restarts the application, so deploy only while the cell is idle.
+- Every start installs `requirements.txt` from PyPI, so the controller needs internet access; without it the install fails and the application never starts.
+- After a deploy, confirm the application started before telling the user it runs. `curl -s http://<controller>/execution-engine/v1/application` returns its `state` and, under `logging`, the install's and the application's logs (parse it with `json.loads(text, strict=False)`: the log text holds raw control characters). A `completed` state with an install error in the logs means it never ran; tell the user what failed.
 - `print` what someone reading the controller's log needs, such as a step starting, a part finished or a fault. An HMI's event stream does not reach the log.
 
 ## Safety

package/skills/vention-machine-logic-hmi/SKILL.md

@@ -3,7 +3,7 @@ name: vention-machine-logic-hmi
 description: Build or edit the custom operator HMI of a MachineLogic application, the React touch screen in customui/ that runs in MachineBuilder and on the MachineMotion pendant, wired to the application's Python process through vention-communication. Use when the user asks for an operator screen, a custom HMI or UI, a touch panel, start and stop buttons, live machine state on screen, or recipes an operator picks, for a Vention machine or inside a directory holding .machine-code-app-directory-info.json. Uses @vention/machine-ui, @vention/machine-apps-components and @vention/machine-logic-ui-sdk. Do not use for the no-code HMI Builder, or for the Python motion logic alone (that is vention-machine-logic).
 license: MIT
 metadata:
-  version: "0.10.14"
+  version: "0.10.15"
   author: Vention
 ---
 
@@ -84,7 +84,7 @@ Blocking SDK calls, cancellation and the shutdown path follow the `vention-machi
 
 - Start the cycle from an `@on_enter_state` handler with `self.spawn(...)`.
 - Never publish a stream or fire a trigger from inside a worker thread. Return to the loop first.
-- Make one thread call per move and check a stop flag between them, so Stop finishes the move in progress. Release what the cycle holds (clamp open, outputs off) before you fire `BaseTriggers.TO_FAULT` or re-raise.
+- Make one thread call per move and check a stop flag between them, so Stop finishes the move in progress. Release what the cycle holds (clamp open, outputs off) before you fire `BaseTriggers.TO_FAULT` or re-raise. `TO_FAULT` does not cancel what `spawn` started. Route the emergency stop from `machine.on_system_state_change` to fault after `await station.cancel_tasks()`, and stop every device in the `lifespan`'s shutdown, as the example's `fault_on_estop` and `stop_devices` do.
 
 ## Live data is a stream
 
@@ -165,14 +165,14 @@ The machine-apps-components README is behind its code: `NavigationBar` takes `Na
 - Confirm anything that starts motion or deletes data in a `VentionModal` with `isTouchDevice`, and say in it what will move.
 - `VentionButton` variants are `filled-brand`, `filled`, `outline`, `text-only`, `shaded` and `destructive`. MUI's `contained` and `outlined` do not exist on it, and neither does a `color` prop.
 - Start is green and Stop is red, both set through the `StatusTopBar` button's `backgroundColor`, `backgroundColorHover` and `textColor`.
-- A `LogsPanel` row cuts `message` and `description` to one line and shows the rest only on hover. Keep `message` to a few words saying what happened, put the cause and what to do next in `description`, and open the whole entry in a `VentionModal` from `onLogClick`.
+- A `LogsPanel` row cuts `message` and `description` to one line and shows the rest only on hover. Keep `message` to a few words saying what happened, put the cause and what to do next in `description`, and open the whole entry in a `VentionModal` from `onLogClick`. Raise every error event as a banner on whatever page is open, whose View button opens that entry on the Logs page, as the example's `app.tsx` does.
 
 ## Validate before you push
 
 1. In the application directory, with the `requirements.txt` packages installed locally: `python3 -c "import server"` to re-emit `proto/app.proto`, and commit it if `git status` shows a change.
 2. In `customui/`: `npm install`, `npm run build`, then `npx tsc --noEmit`, and check that `ui/index.html` exists and loads its script from `./assets/`, a relative path.
 3. `vention push`, then open the HMI from the MachineLogic tab in MachineBuilder and run it on the digital twin before any hardware run. Inside the MachineBuilder tab the browser's element search can't see the HMI's controls, so take a screenshot and tap by coordinates, and take a fresh screenshot after each tap since the layout moves.
-4. Read `vention logs` when a command fails; the server's errors land there. On a real controller, read them as the `vention-machine-logic` skill's "Deploying to a real cell" says.
+4. Read `vention logs` when a command fails; the server's errors land there. On a real controller, confirm the application started and read its logs as the `vention-machine-logic` skill's "Deploying to a real cell" says.
 
 ## Safety
 
@@ -180,7 +180,7 @@ The HMI drives physical machinery that can injure someone.
 
 - Start never fires on page load, on reconnect, or from a stream message. Only an operator's tap, confirmed in a modal, starts motion.
 - Start and Stop live in the `StatusTopBar`, so they are on every page. Do not repeat them on a page. Raise the bar above `theme.zIndex.modal`, as the example's `app.tsx` does, or an open `VentionModal` covers Stop.
-- Stop stays enabled unless the station is known to be ready or already stopping, as the example's `canStop` does. A fault is neither, so Stop stays enabled there, and so it does while the stream is disconnected: a dropped stream may hide a moving machine. Every other command is disabled while disconnected.
+- Stop is disabled until this page load has received its first status, since no Stop can reach the app before then; show why next to it and say to use the emergency stop if the machine moves. After that, Stop stays enabled unless the station is known to be ready or already stopping, as the example's `canStop` does. A fault is neither, so Stop stays enabled there, and so it does while the stream is disconnected: a dropped stream may hide a moving machine. When Stop fails, say it did not reach the station and to use the emergency stop. Every other command is disabled while disconnected.
 - A tap on Stop shows at once. While the station stops, the Stop button reads "Stopping…" (derive that label from the streamed state and `connected`, as the example's `isStopping(status, connected)` does, never from a tapped flag alone: once the stream drops it reads "Stop" again and stays pressable), the Operate page's progress bar marks where the run now ends (the cycle in progress amber, the cancelled ones hatched and struck through), and a line by the heading says the emergency stop halts at once. Say it on the screen the operator already watches rather than in a separate alert.
 - Send Start with a `timeoutMs` and an abort signal, and abort it when the stream drops. A Start the operator can no longer see must not land later; say it was not confirmed and to check the station.
 - The HMI never offers a way around an emergency stop, safety interlock, light curtain or guard, not even a hidden one for testing.
@@ -190,7 +190,7 @@ The HMI drives physical machinery that can injure someone.
 
 `examples/indexing-station-hmi/` indexes a part on a conveyor, clamps it, proves the clamp closed, dwells and releases, for the cycle count of the recipe the operator picked.
 
-- `server.py`: the state machine, the streams, the Start action, both bundles, and `Machine()` in the `lifespan`.
+- `server.py`: the state machine, the streams, the Start action, both bundles, `Machine()` in the `lifespan`, the emergency stop routed to fault, and every device stopped on shutdown.
 - `models.py`: the `Recipe` storage model, every field with a zero default.
 - `project.json`, `requirements.txt`: the one process and the exact pins.
 - `proto/app.proto`: what `finalize()` emits.
@@ -216,7 +216,7 @@ The HMI drives physical machinery that can injure someone.
 - `size` left at the `"small"` default on a touch screen.
 - `BrowserRouter`, whose routes miss under `.../index.html`.
 - Reading versions from `ui/package.json`; the manifest is `customui/package.json`.
-- Disabling Stop whenever the stream drops.
+- Disabling Stop whenever the stream drops, or enabling it before the page has ever connected.
 - A Stop that looks the same before and after the tap while the station finishes its move.
 - The state shown in the `StatusTopBar` and again on a page.
 - `severity="warning"` on a `VentionAlert`. It is `"warn"`.

package/skills/vention-machine-logic-hmi/examples/indexing-station-hmi/customui/src/app.tsx

@@ -4,7 +4,7 @@ import { NavigationBar, StatusTopBar } from "@vention/machine-apps-components"
 import type { LogEntry, LogType } from "@vention/machine-apps-components"
 import { COLORS, VentionAlert, VentionModal } from "@vention/machine-ui"
 import { useEffect, useRef, useState } from "react"
-import { Navigate, Route, Routes } from "react-router-dom"
+import { Navigate, Route, Routes, useNavigate } from "react-router-dom"
 import { client, openEvents, openStatus, STATUS_STALL_MS } from "./client"
 import type { Event, Recipe } from "./gen/app_pb"
 import { LogsPage } from "./pages/logs-page"
@@ -52,6 +52,11 @@ export function App() {
   const { value: status, connected } = useStream(openStatus, STATUS_STALL_MS)
   const logEntries = useEventLog()
   const [commandError, setCommandError] = useState("")
+  const navigate = useNavigate()
+  // Every error event raises a banner on whatever page is open; View opens the whole entry on the Logs page.
+  const [errorEntry, setErrorEntry] = useState<LogEntry | undefined>(undefined)
+  const [openLogEntry, setOpenLogEntry] = useState<LogEntry | undefined>(undefined)
+  const latestEntry = logEntries[0]
   const state = describeState(status, connected)
 
   const [recipe, setRecipe] = useState<Recipe | undefined>(undefined)
@@ -63,6 +68,16 @@ export function App() {
     if (!connected) startRequest.current?.abort()
   }, [connected])
 
+  useEffect(() => {
+    if (latestEntry?.level === "error") setErrorEntry(latestEntry)
+  }, [latestEntry])
+
+  const viewError = () => {
+    setOpenLogEntry(errorEntry)
+    setErrorEntry(undefined)
+    navigate("/logs")
+  }
+
   const start = async () => {
     setConfirmingStart(false)
     if (recipe === undefined) return
@@ -77,7 +92,9 @@ export function App() {
   }
 
   const stop = () => {
-    client.trigger_Stop({}).catch((error: unknown) => setCommandError(`Stop failed: ${errorText(error)}`))
+    client
+      .trigger_Stop({})
+      .catch((error: unknown) => setCommandError(`Stop did not reach the station (${errorText(error)}). Use the emergency stop.`))
   }
 
   return (
@@ -111,6 +128,27 @@ export function App() {
           ]}
         />
       </Box>
+      {status === undefined && (
+        <VentionAlert
+          severity="warn"
+          size="xx-large"
+          title="Not connected to the app yet"
+          descriptionText="Stop is available once the app answers. Use the emergency stop if the machine moves."
+          isFullWidth
+        />
+      )}
+      {errorEntry !== undefined && (
+        <VentionAlert
+          severity="error"
+          size="xx-large"
+          title={errorEntry.message}
+          primaryButtonText="View"
+          onPrimaryButtonClick={viewError}
+          isFullWidth
+          isCloseable
+          onCloseButtonClick={() => setErrorEntry(undefined)}
+        />
+      )}
       {commandError !== "" && (
         <VentionAlert
           severity="error"
@@ -130,7 +168,7 @@ export function App() {
             }
           />
           <Route path="/recipes" element={<RecipesPage connected={connected} onError={setCommandError} />} />
-          <Route path="/logs" element={<LogsPage entries={logEntries} />} />
+          <Route path="/logs" element={<LogsPage entries={logEntries} openEntry={openLogEntry} onOpenEntry={setOpenLogEntry} />} />
           <Route path="*" element={<Navigate to="/" replace />} />
         </Routes>
       </Box>

package/skills/vention-machine-logic-hmi/examples/indexing-station-hmi/customui/src/pages/logs-page.tsx

@@ -2,7 +2,7 @@ import { LogsPanel } from "@vention/machine-apps-components"
 import type { FetchParams, FetchResult, LogEntry, LogType } from "@vention/machine-apps-components"
 import { VentionModal } from "@vention/machine-ui"
 import type { VentionModalProps } from "@vention/machine-ui"
-import { useCallback, useState } from "react"
+import { useCallback } from "react"
 
 const PAGE_SIZE = 10
 const MODAL_TYPE: Record<LogType, VentionModalProps["type"]> = { error: "negative", warning: "warning", info: "info" }
@@ -15,8 +15,14 @@ function matchesFilters(entry: LogEntry, { filters }: FetchParams): boolean {
   return true
 }
 
-export function LogsPage({ entries }: { entries: LogEntry[] }) {
-  const [openEntry, setOpenEntry] = useState<LogEntry | undefined>(undefined)
+type LogsPageProps = {
+  entries: LogEntry[]
+  // Held by the app, so the error banner can open its entry here.
+  openEntry: LogEntry | undefined
+  onOpenEntry: (entry: LogEntry | undefined) => void
+}
+
+export function LogsPage({ entries, openEntry, onOpenEntry: setOpenEntry }: LogsPageProps) {
   const dataFetcher = useCallback(
     async (params: FetchParams): Promise<FetchResult> => {
       const matching = entries.filter(entry => matchesFilters(entry, params))

package/skills/vention-machine-logic-hmi/examples/indexing-station-hmi/customui/src/station.ts

@@ -22,10 +22,13 @@ const STATE_DISPLAY: Record<string, StateDisplay> = {
   Station_stopping: { label: "Stopping", color: COLORS.amber[500] },
   fault: { label: "Fault", color: COLORS.red[600] },
 }
+const CONNECTING: StateDisplay = { label: "Connecting…", color: COLORS.slate[400] }
 const DISCONNECTED: StateDisplay = { label: "Disconnected", color: COLORS.slate[400] }
 
+// `status` stays set once the stream has delivered, so undefined means this page has never connected.
 export function describeState(status: StationStatus | undefined, connected: boolean): StateDisplay {
-  if (!connected || status === undefined) return DISCONNECTED
+  if (status === undefined) return CONNECTING
+  if (!connected) return DISCONNECTED
   return STATE_DISPLAY[status.state] ?? { label: status.state, color: COLORS.slate[500] }
 }
 
@@ -37,9 +40,12 @@ export function isStopping(status: StationStatus | undefined, connected: boolean
   return connected && status?.state === "Station_stopping"
 }
 
-/** Stop is disabled only when the station is known to be ready or already stopping: a dropped stream may hide a moving conveyor. */
+/**
+ * Stop waits for the first connection, since before it no Stop can reach the app. After that it is disabled only
+ * when the station is known to be ready or already stopping: a dropped stream may hide a moving conveyor.
+ */
 export function canStop(status: StationStatus | undefined, connected: boolean): boolean {
-  return !(connected && status?.state === "ready") && !isStopping(status, connected)
+  return status !== undefined && !(connected && status.state === "ready") && !isStopping(status, connected)
 }
 
 export function errorText(error: unknown): string {

package/skills/vention-machine-logic-hmi/examples/indexing-station-hmi/server.py

@@ -1,6 +1,7 @@
 """Indexing station with an operator HMI: index, clamp, prove the clamp, dwell, release, per recipe cycle.
 
 Needs actuator "Conveyor", output "Clamp" and input "Clamp Closed"; customui/ calls it only through the generated client.
+An emergency stop sends the station to fault, and shutting the server down stops the conveyor and opens the clamp.
 """
 
 import asyncio
@@ -16,6 +17,7 @@ from pydantic import BaseModel
 from communication.app import VentionApp
 from communication.decorators import action, stream
 from machinelogic import Machine, MotionProfile
+from machinelogic.ivention.imachine import MachineOperationalState, MachineSafetyState
 from state_machine.core import BaseStates, BaseTriggers, StateMachine
 from state_machine.decorators import on_enter_state, on_state_change
 from state_machine.defs import State, StateGroup, Trigger
@@ -155,6 +157,20 @@ class IndexingStation(StateMachine):
         if self.machine is not None:
             self.machine.get_output("Clamp").write(False)
 
+    def stop_devices(self) -> None:
+        if self.machine is not None:
+            self.machine.get_actuator("Conveyor").stop()
+            self.release()
+
+    async def fault_on_estop(self) -> None:
+        # The to_fault trigger does not cancel the cycle task, so cancel it first.
+        await self.cancel_tasks()
+        self.fault_message = "emergency stop pressed"
+        self.trigger(BaseTriggers.TO_FAULT.value)
+        await publish_event(
+            "error", "Emergency stop", "Release the emergency stop and check the station, then press Reset on the Operate page."
+        )
+
     async def release_safely(self) -> None:
         try:
             await asyncio.to_thread(self.release)
@@ -218,14 +234,26 @@ async def repeat_status() -> None:
 
 @asynccontextmanager
 async def lifespan(_: FastAPI) -> AsyncIterator[None]:
+    loop = asyncio.get_running_loop()
+
+    def on_safety(_operational: MachineOperationalState, safety: MachineSafetyState) -> None:
+        if safety == MachineSafetyState.EMERGENCY_STOP:
+            asyncio.run_coroutine_threadsafe(station.fault_on_estop(), loop)
+
     try:
         station.machine = await asyncio.to_thread(Machine)
+        station.machine.on_system_state_change(on_safety)
     except Exception as error:
         station.fault_message = f"cannot reach the controller: {error}"
     await publish_status()
     heartbeat = asyncio.create_task(repeat_status())
-    yield
-    heartbeat.cancel()
+    try:
+        yield
+    finally:
+        heartbeat.cancel()
+        # Cancelling the cycle does not stop a move already running in its thread.
+        await station.cancel_tasks()
+        await asyncio.to_thread(station.stop_devices)
 
 
 app = VentionApp(name="IndexingStation", emit_proto=True, proto_path="proto/app.proto", lifespan=lifespan)

package/skills/vention-monitoring/SKILL.md

@@ -3,7 +3,7 @@ name: vention-monitoring
 description: Diagnose deployed Vention machines from controller state, history, health, and activity data. Use when the user reports a machine that is down, faulted, offline, slow, or underperforming, asks why a cycle time regressed, wants to interpret MachineMotion event data or drive and brake status, asks about OEE or uptime, or wants to know which machine in a fleet needs attention. Trigger on a MachineMotion serial number plus any complaint.
 license: MIT
 metadata:
-  version: "0.10.14"
+  version: "0.10.15"
   author: Vention
 ---