Skip to content

Note

Letting an agent write to a control system

Giving a language model a read of a building is a documentation problem. Giving it a write is a safety problem, and the gates that make it survivable are not the ones people reach for first.

  • Agents
  • Permissions
  • Station engineering

Written

A write is a plant movement at a priority

In an ordinary program a write sets a variable. In a control system it enters a priority array, competing with everything else that wants the same output, and the result depends on what else is writing and at what level. Nothing about the call tells you that. The verb is the same length as any other.

So the first thing an agent integration has to get right is not the protocol. It is that a successful write is not the same as a correct one, and that the mechanism which decides the outcome lives at the station in the point's priority levels rather than in the request.

Visible does not mean writable

On a Niagara station, exposing a writable point over oBIX is a deliberate act: an export descriptor is added under the oBIX network, naming the point and the priority level the write should land on, and the framework makes the link so that contention is resolved in one place rather than at the protocol edge. Only point types that have priority input slots are valid candidates.

Point Can it be exported as writable?
Boolean, Enum, Numeric and String writable points Yes. These are the four types with priority input slots, which is what the descriptor needs in order to land the write at a chosen level.
Everything else, including read-only points No. And a point being visible in the tree says nothing about whether a write to it will be accepted — visibility and writability are two separate acts of engineering.

It is tempting to read that as a gift — the station keeping a list of what an outside caller is allowed to move, maintained by whoever engineered it. It is not. The descriptor is how a write lands at a chosen priority. It is not what decides whether a write is accepted, and the difference matters enough to spend a section on.

The export list is not the fence

A Niagara station serves oBIX from a servlet with three verbs, and the write verb is PUT. Follow what the driver does with one and the export descriptor never appears. The handler takes the object the URI resolved to; if that object implements the framework's writable-over-oBIX interface it hands over, and otherwise it decodes the body, walks down to the property's owning container, and performs an ordinary framework property set — passing the oBIX user along as the context.

The handover branch is dead code on a stock station. We looked for implementations of that interface across every one of the 756 module jars in a stock 4.15 install: there are none. The only two classes that so much as name it are the interface itself and the utility class performing the instanceof check. So every PUT a station accepts goes down the generic property-set path, and that path does not consult the Exports folder, a descriptor, or any allow-list at all.

An unexported point is not a protected point. The inference worth unlearning is the reassuring one: not "visible does not mean writable", which is true and which everybody already says, but its converse — that a property nobody exported is therefore out of reach. Nothing in the write path enforces that.

So what does stop a write? Two things, and only two. The first is the station's own permission model: the property set is performed as the oBIX user, so the framework checks that user's permissions against the category of the target component, exactly as it would for the same user in Workbench. When that check fails the driver catches the framework's permission exception and re-throws it as an oBIX fault reading <user> cannot write this object. The second is a single hardcoded refusal: the source and classFile properties of a program object are rejected by name, because writing those is writing code.

That is the whole list. The boundary an integrator has to reason about is a permission model expressed in categories and user roles — engineered per user, invisible in every document the protocol lets a client read.

What people expect to be the boundary What the code actually does
The Exports folder lists what may be written The write handler never reads it. It lists what may be written at a chosen priority, through a link — a different mechanism.
A write to a point is a PUT to the point Through a descriptor it is a POST to an op the descriptor advertises. The descriptor sets its own output slot and the link carries the value onward.
The descriptor keeps writes off override levels It forbids exactly one value — "none". Every real priority, 1 through 16, is selectable; the default is 10 because someone chose 10.
A refused write and a refused command fail the same way Only the write path converts a permission failure into a well-formed oBIX fault. The invoke path has no such handler.

None of this is a defect in the driver. A protocol adapter that re-implemented the framework's permission model would be a second place for it to be wrong, and delegating to the real one is the correct design. It is a defect in how the thing is usually described — including, until we read the bytecode, by us.

The consequence for an agent is the opposite of reassuring, and it is why this bridge is built the way the next section describes. The station cannot tell a client what that client is allowed to write. So a tool surface that wants a fence has to bring its own.

Two gates, and a tool that is absent rather than refusing

A tool surface an agent is given at run time should express permission structurally, not conversationally. Two independent decisions, made by the operator and not by the model:

The first is whether this deployment may write at all. The second is where it may write — a path prefix, so a bridge pointed at a whole station can still be allowed to move exactly one subtree.

The detail that matters is what happens when writes are off: the write tool is not advertised. It does not appear in the list of available tools at all, rather than appearing and refusing. A tool that exists and says no is a negotiation, and a model that has been told no by a tool it can see will try a different phrasing, a different path, or a batch operation. A capability that is absent from the surface cannot be talked into existing.

Read-only by default, and off is the resting state. The interesting property of a two-gate design is not that it can be locked down. It is that the locked-down configuration is the one you get by doing nothing.

The type is the element name, so guessing is a fault

oBIX types a value by the element name it arrives in, and not by anything about the value. A set point of 21.5 sent as a string is a string write. Any client that infers the element from the shape of the value will be right most of the time, which is the worst possible failure rate for something that moves plant.

So the type belongs in the call, stated by whoever made the decision, and a tool that asks for it explicitly is not being awkward. More generally: an agent-facing tool should refuse to supply defaults for the arguments a person would have had to think about. This is what the protocol surface actually looks like once read out of a station's own code rather than the standard.

Polling floors exist for the controller's sake

A controller is not a server. The vendor documentation for the oBIX point extension says the watch interval defaults to two seconds and recommends raising it to ten or more to reduce load. An agent asking for a subscription has no idea it is talking to a device with a fraction of a laptop's headroom, and will happily ask for one second because the number sounded responsive.

The fix is not to document a floor. It is to enforce one — clamp the requested interval up, cap the number of concurrent subscriptions, cap how many points one subscription may carry. This installation contains no compiled-in ceiling on any of those, so nothing at the station will stop a client that behaves badly. The client has to stop itself, and the same logic covers every other poll rate on the station.

What the operator can see afterwards

Every write an agent makes should be answerable a week later: what was sent, to what, at what level, and on whose authority. Two things make that cheap. The bridge — in our case obix-mcp, which is where everything in this note was worked out — runs under a named station user, so the station's own audit trail carries the whose; and the raw request and reply bodies can be dumped to a log for the run that matters, which is also the only honest way to confirm a client and a real station agree about a body the documentation never shows.

The credentials must not travel with that log. Dumping the traffic is useful; dumping the header that authorises it is a way of turning a debugging session into an incident.

What none of this proves

Gates, floors and an audit trail make an agent's writes reviewable. They do not make the agent's judgement sound, and no amount of protocol design will. The question of whether a model should be moving a set point on an occupied building at all is a question for the people who own the building, and the honest answer today is that the read side is useful now and the write side is worth building carefully and switching on last.

It is also worth being precise about what has been tested. Writing a client against a station's own bytecode and proving it against a fixture built from that evidence shows that the client and the evidence agree. It does not show that a controller agrees. Until it has been pointed at one, that distinction is the whole difference between a working integration and a plausible one.

That applies with particular force to the section above. Reading a handler and finding no allow-list in it establishes what the handler does; it does not establish what a given station will accept, because the thing we found in its place — a permission check against the target's category — is configuration, not code, and differs on every site. The claim being made is narrow and deliberately so: the refusal, when one comes, will come from the permission model rather than from the export list. Pointing a PUT at an unexported property on a real controller and recording which of the two answers back is on the list of things to confirm, not the list of things shown.

Sources

Where this is written down

Related

Where this comes up in the work

More notes

Other things worth writing down

Next step

Tell us the version, the hardware, and what it has to do.

You will get a written scope back, and a clear answer on whether we are the right team for it. If the honest answer is that you do not need us, you will get that instead.