Capability Packs

A capability pack adds protocol tools to the agent's tool surface. Packs are compiled into the binary and enabled per project in configuration. There is nothing to install.

Once a pack is on, its tools are called exactly like Read or Bash. The agent can open a socket to a device, read a register, and act on the value inside the same turn that wrote the code.

Available packs

Pack	Module key	Tools	Checks
Modbus	modbus	2	2
OPC UA	opcua	3	5
EtherCAT	ethercat	9	4
IEC 61131	iec61131	0	1

Fourteen protocol tools in total. Each pack also contributes conformance checks. See Conformance Checks.

Modbus

Reads and writes Modbus registers over TCP and RTU.

Tool	Tier	What it does
ModbusRead	Safe	Read holding or input registers from a device
ModbusWrite	Hard stop	Write to holding registers on a device

OPC UA

Browses and accesses the address space of an OPC UA server.

Tool	Tier	What it does
OpcUaBrowse	Safe	Browse the address space of a server
OpcUaRead	Safe	Read values from specific nodes
OpcUaWrite	Hard stop	Write values to writable nodes

EtherCAT

Discovery, SDO access and live process-data I/O on an EtherCAT segment.

Tool	Tier	What it does
EtherCatScan	Safe	Scan a segment and report the SubDevices found
EtherCatIdentify	Safe	Identify SubDevices by vendor and product code
EtherCatSdoRead	Safe	Read a Service Data Object from a SubDevice
EtherCatSdoWrite	Hard stop	Write a Service Data Object to a SubDevice
EtherCatReadIo	Safe	Read process data from the live I/O session
EtherCatWriteIo	Hard stop	Write process data, which energises physical outputs
EtherCatPulseIo	Hard stop	Pulse an output for a bounded duration
EtherCatGoOperational	Hard stop	Bring the segment to the OP state
EtherCatStopIo	Mutating	Stop the live I/O session and release outputs

EtherCAT tools drive physical outputs

EtherCatWriteIo, EtherCatPulseIo, EtherCatSdoWrite and EtherCatGoOperational are hard-stop tools. They prompt in every permission mode, and --skip-permissions does not waive that. See Permission Model.

The live I/O session

A live I/O session holds physical outputs energised between turns. It appears in /jobs, so you can stop it yourself without the agent's cooperation. If the model gets stuck, you are not reduced to killing the process.

Restricting which interfaces may be acquired

With the ethercat module on, acquiring a segment is already permitted and every attempt prompts. --ethercat-acquire-bus is a restriction, not a grant: pass it to put other interfaces off limits on a host with more than one fieldbus port.

# Only eth1 may be acquired; every other interface is refused
oasis-agent --ethercat-acquire-bus eth1

# Repeat the flag to allow a second
oasis-agent --ethercat-acquire-bus eth1 --ethercat-acquire-bus eth2

Capabilities

EtherCAT is raw layer 2, so it needs CAP_NET_RAW to open the socket and CAP_NET_ADMIN to read the interface MTU. oasis-agent install and update grant these automatically: as root, via sudo where no password is needed, or by prompting on the terminal.

Where none of those are possible the install still succeeds and prints the setcap command to run. See Installing & Updating.

oasis-agent doctor reports whether the running process and the installed binary have them. Modbus and OPC UA are ordinary TCP and need none of this.

Device names

Vendor identification needs no configuration. The ETG's published vendor register is compiled into the binary, so EtherCatIdentify names the brand of essentially any device out of the box.

Product names are not embedded. There are tens of thousands of parts, they run to tens of megabytes, and they are revised constantly. Without configuration, product_name comes back null with a reason and a remedy, never a guess.

Point ethercat_catalogue at a directory of vendor ESI XML files and the parts get names. Those files are usually already on the engineering PC; TwinCAT keeps its library under Config/Io/EtherCAT.

IEC 61131

The IEC 61131 module ships checks and guidance, not tools. It contributes one conformance check covering Structured Text toolchain availability.

Oasis CLI is a build orchestrator, not a toolchain vendor

Structured Text is compiled by a toolchain mutexer deliberately does not carry. Rather than writing ST into a repository that cannot build it, the agent is directed to say so.

If you need ST compilation, supply the toolchain. This module tells you whether it is present and usable.

Enabling packs

Packs are opt-in. Set the modules key in ./.oasis/config.json or ~/.oasis/config.json:

{
  "modules": {
    "ethercat": true,
    "opcua": true
  }
}

Only keys present in the modules object are loaded. An unknown key is a hard error, not a silent no-op. A typo fails at startup rather than quietly producing a run with no tools.

A disabled pack registers nothing, contributes nothing to the prompt, and does not affect the cache key.

Confirm what a run actually loaded:

oasis-agent --show-config

Pack configuration keys

Some packs need a path as well as the module toggle. These name a directory an operator sets once, so they live only in the config file. Set them with /config <key> <value> or by editing the file directly.

Key	Pack	Points at
ethercat_catalogue	EtherCAT	A directory of vendor ESI XML files, for product-name resolution
checks_catalogue	All	A directory of descriptor TOML layered over the built-in check catalogue by check id

How packs affect the cache

The tool schema is part of the prompt prefix the model server caches, so the tool set is part of the cache key.

Configuration	Cache behaviour
Unchanged between runs	100% prefix reuse, across turns and across processes
A pack enabled or disabled	Cold slot; the whole prompt is reprocessed once (~13 k tokens)

The practical rule: decide your pack configuration per project and leave it alone. Toggling packs mid-session is the one routine action that costs a full prefill.