@aryacode/dsh-engineering 0.4.5 → 0.4.6

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## [0.4.6] - 2026-10-25
+
+### Added
+
+The EtherNet/IP surface now uses the driver rather than one corner of it. Five new tools, all under the
+L5X product row's `live` switch:
+
+- `read_live_tags` — up to 64 declared scalars in **one** request (CIP tag group) instead of one
+  connection-and-read per tag.
+- `read_controller_clock` — controller identity plus the wall clock beside the workstation clock and the
+  offset between them; reports "unsupported" on non-L8x models instead of guessing.
+- `discover_controllers` — bounded UDP broadcast discovery: address, product, revision, serial, status.
+  Needs no address and no export.
+- `write_live_tag` — one declared scalar, **approval-gated**, then read back over CIP so the result is
+  the controller's own value.
+- `write_controller_clock` — set the wall clock (L8x), approval-gated, read back.
+
+### Safety
+
+- Writes need **two** independent switches: the row's new `allowWrites` config (off by default) **and** a
+  human approving that exact operation. With `allowWrites` on and a `never` approval policy the tool
+  refuses with `APPROVAL_UNAVAILABLE`; a declined prompt is `APPROVAL_DENIED`. Nothing reaches a
+  controller before both pass.
+- Every write validates against the open export first: declared, not an alias, no array dimensions,
+  `ExternalAccess` not `None`, value inside the declared type and range (BOOL boolean; INT/DINT integer
+  within range; REAL finite).
+- A write whose readback differs from the requested value fails with `WRITE_NOT_VERIFIED` rather than
+  reporting success.
+- `test/live.spec.ts` covers the gating: switch off, policy `never`, declined prompt, wrong value type,
+  and a UDT tag refused as non-scalar — 70 tests in the package.
+
 ## [0.4.5] - 2026-10-25
 
 ### Changed

package/README.md

@@ -4,7 +4,7 @@
 MotionWorks IEC and FactoryTalk Optix sit behind a single install, one row per surface. A row is the
 switch: disable it and that plugin unloads, so its tool schemas leave the request.
 
-`@aryacode/dsh-engineering` · 79 tools · 5 rows · 4 products · MIT
+`@aryacode/dsh-engineering` · 84 tools · 5 rows · 4 products · MIT
 
 ---
 
@@ -21,7 +21,8 @@ the row, off by default, so a read-only profile pays for the read tools and noth
 |---|---|---|---|
 | `l5x` | `editing` | off | the nine `draft_*` schemas |
 | `l5x` | `studio` | off | the Logix Designer SDK and supervised controller schemas |
-| `l5x` | `live` | off | the EtherNet/IP polling and trend schemas |
+| `l5x` | `live` | off | the EtherNet/IP read, batch, discovery, clock and trend schemas |
+| `l5x` | `allowWrites` | off | the two approval-gated writes (tag, wall clock) |
 | `ftview` | `edit`, `studio` | on | staged ME edits and the Studio handoff |
 | `mwi` | `edit` | off | the seven MotionWorks edit schemas |
 
@@ -33,7 +34,7 @@ bundle.
 
 | Product | Tools | Default | Needs |
 |---|---|---|---|
-| **Studio 5000 L5X** | 35 | read on; edit, Studio, live **off** | Node for offline reads; Studio 5000 + Logix Designer SDK for SDK work; a controller for live |
+| **Studio 5000 L5X** | 40 | read on; edit, Studio, live **off** | Node for offline reads; Studio 5000 + Logix Designer SDK for SDK work; a controller for live |
 | **FactoryTalk View ME** | 14 | all on | Node for an export folder; FactoryTalk View Studio ME for discovery and the handoff |
 | **MotionWorks IEC** | 24 | session, read, verify on; edit **off** | MotionWorks IEC 3 Pro installed; verified against 1.19 |
 | **FactoryTalk Optix** | 6 | on | Optix Studio installed |
@@ -41,7 +42,7 @@ bundle.
 Tool groups, by product:
 
 - **L5X** — 11 read (`open_project` … `compare_projects`), 9 staged drafts (`draft_*`), 6 Logix
-  Designer SDK, 7 supervised controller, 2 live EtherNet/IP
+  Designer SDK, 7 supervised controller, 7 live EtherNet/IP (2 reads, 2 identity/discovery, 1 batch read, 2 approval-gated writes)
 - **FactoryTalk View** — 6 read, 5 staged edits, 3 Studio handoff
 - **MotionWorks IEC** — 7 session, 7 saved-project reads, 3 verify, 7 staged edits
 - **Optix** — 6 tools, unlinked to a skill until one exists
@@ -55,7 +56,7 @@ down:
 
 | Row | Mounts | Config options (default) |
 |---|---|---|
-| `l5x` | offline reads, checks, comparison and the `rockwell-l5x` guidance; optionally drafts, SDK, live | `editing` (off), `studio` (off), `live` (off) |
+| `l5x` | offline reads, checks, comparison and the `rockwell-l5x` guidance; optionally drafts, SDK, live (reads, batch, discovery, clock) and supervised writes | `editing` (off), `studio` (off), `live` (off), `allowWrites` (off) |
 | `ftview` | FactoryTalk View ME read, guidance and edits; optionally the Studio handoff | `edit` (on), `studio` (on) |
 | `mwi` | MotionWorks IEC session, reads, verify and guidance; optionally the edits | `edit` (off) |
 | `viewers` | ladder + ME display previews | — |
@@ -86,19 +87,20 @@ Where each surface actually stands, based on what has been exercised.
 - Logix Designer SDK: a real ACD exported to a 3.0 MB L5X against SDK v37
 - Supervised controller access — upload, mode change and download behind per-call approval, with
   downloads accepting only a verification id produced by a passed build
-- Live EtherNet/IP reads and a bounded PLC trend
+- Live EtherNet/IP: polling, one-request batch reads of up to 64 tags, controller identity and clock, LAN discovery, and a bounded trend
+- Supervised live writes: `write_live_tag` and `write_controller_clock` need the row's `allowWrites` switch **and** per-call human approval, and report the value the controller reads back
 - FactoryTalk View ME: export reads, structural checks, comparison, staged display and HMI tag edits
 - MotionWorks IEC: verified live against 3 Pro 1.19 — stage, start, worksheet, close, saved-project
   reads, compile diagnostics, code replacement, declaration add, POU create/delete, block insertion
   and a POU package export/delete/import round trip
 - Ladder viewer and FactoryTalk View display preview
 
-**Deliberately off by default** — enabled per profile: `l5x-editing`, `l5x-studio`, `l5x-live`,
+**Deliberately off by default** — enabled per profile: `l5x-editing`, `l5x-studio`, `l5x-live`, `allowWrites`,
 `mwi-edit`. A read-only profile should not pay for nine draft schemas or a controller surface.
 
 **Known limits** — stated in the bundle, not hidden:
 
-- Live reads and SDK builds cannot establish that online logic matches the export; every result says
+- Live reads, SDK builds and live writes cannot establish that online logic matches the export; every result says
   so in `coverage`
 - FBD/SFC semantics are not exercised
 - FactoryTalk View Studio work is a **manual handoff**: the bundle plans the import and preflights
@@ -113,6 +115,7 @@ Where each surface actually stands, based on what has been exercised.
 |---|---|
 | **0.4.4** | One row per product: five rows, optional surfaces moved into each row's config |
 | **0.4.0** | Both previews fold into the bundle's own client face — one package, one browser bundle, 16 rows |
+| **0.4.6** | Full EtherNet/IP surface: batch reads, discovery, controller clock, and approval-gated tag and clock writes; 84 tools |
 | **0.3.0** | FactoryTalk Optix becomes a bundle component; 79 tools total |
 | **0.2.0** | MotionWorks IEC ports into the bundle — 24 tools over the COM bridge and saved-model engine, verified live; edit off by default |
 | **0.1.2** | Harness filesystem contract fixed across L5X and FactoryTalk View; every L5X tool linked to its capability by name; generated tool reference, examples and architecture docs |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aryacode/dsh-engineering",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "description": "AryaCode engineering bundle: one install surface for the Studio 5000 L5X, FactoryTalk View ME, MotionWorks IEC and FactoryTalk Optix surfaces, one row per product, with the ladder and display previews.",
   "keywords": [
     "dsh",

package/vendor/l5x/cip-worker.mjs

@@ -0,0 +1,181 @@
+/** Isolated one-shot EtherNet/IP transactions. The parent owns deadlines, approval and validation. */
+import { isMainThread, parentPort, workerData } from 'node:worker_threads'
+import { setTimeout as delay } from 'node:timers/promises'
+import ethernetIp from 'st-ethernet-ip'
+import { isIPv4 } from 'node:net'
+
+/** Shape one tag address for output. */
+function addressOf(entry) {
+  return entry.program === undefined ? entry.name : `Program:${entry.program}.${entry.name}`
+}
+
+/** One observed value, quality included. */
+function readValue(entry, tag) {
+  const typeMatches = tag.type === entry.data_type
+  const scalar = typeof tag.value === 'boolean' || (typeof tag.value === 'number' && Number.isFinite(tag.value))
+  return {
+    tag: addressOf(entry),
+    data_type: entry.data_type,
+    actual_data_type: tag.type,
+    value: typeMatches && scalar ? tag.value : null,
+    quality: typeMatches && scalar ? 'good' : 'bad',
+    ...typeMatches && scalar ? {} : { error: 'Live type or value differs from the export declaration' },
+  }
+}
+
+/**
+ * Open a controller, run one operation, and always close the connection.
+ *
+ * @param {object} spec Validated worker request.
+ * @returns {Promise<object>} The operation's result value.
+ */
+async function connectAndRun(spec, run) {
+  if (!spec || typeof spec.ip !== 'string' || !isIPv4(spec.ip) || !Number.isInteger(spec.slot) || spec.slot < 0 || spec.slot > 31
+    || !Number.isInteger(spec.timeout) || spec.timeout < 1)
+    throw new Error('Invalid CIP worker request')
+  const plc = new ethernetIp.Controller(false)
+  plc.timeout_sp = spec.timeout
+  // Driver transport failures are reported per request; keep the socket event handled.
+  plc.on('error', error => { void error })
+  try {
+    await plc.connect(spec.ip, spec.slot, false)
+    await plc.readControllerProps()
+    const controller = {
+      product_name: plc.properties.name,
+      serial_number: plc.properties.serial_number,
+      revision: plc.properties.version,
+      status: plc.properties.status,
+    }
+    return await run(plc, controller)
+  } finally {
+    // Unconnected explicit messaging needs no Forward Close request.
+    const closed = new Promise(resolve => plc.once('close', resolve))
+    if (!plc.closed) { if (!plc.destroyed) plc.destroy(); await closed }
+  }
+}
+
+/** Batch read: one explicit request carries every tag in the group. */
+async function read(spec) {
+  return await connectAndRun(spec, async (plc, controller) => {
+    const group = new ethernetIp.TagGroup()
+    const tags = spec.tags.map(entry => {
+      if (!entry || typeof entry.name !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/u.test(entry.name)
+        || !['BOOL', 'INT', 'DINT', 'REAL'].includes(entry.data_type)
+        || (entry.program !== undefined && (typeof entry.program !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/u.test(entry.program))))
+        throw new Error('Invalid CIP worker tag')
+      const tag = new ethernetIp.Tag(entry.name, entry.program)
+      group.add(tag)
+      return { entry, tag }
+    })
+    await plc.readTagGroup(group)
+    return {
+      controller,
+      request_count: 1,
+      observed_at: new Date().toISOString(),
+      values: tags.map(({ entry, tag }) => ({ ...readValue(entry, tag), observed_at: new Date().toISOString() })),
+    }
+  })
+}
+
+/** Identity and wall clock; the clock exists only on L8x controllers. */
+async function clock(spec) {
+  return await connectAndRun(spec, async (plc, controller) => {
+    try {
+      await plc.readWallClock()
+      return {
+        controller,
+        supported: true,
+        controller_time: plc.properties.time instanceof Date ? plc.properties.time.toISOString() : String(plc.properties.time),
+        host_time: new Date().toISOString(),
+      }
+    } catch (error) {
+      return {
+        controller,
+        supported: false,
+        host_time: new Date().toISOString(),
+        reason: error instanceof Error ? error.message : 'Wall clock is unavailable on this controller',
+      }
+    }
+  })
+}
+
+/** One tag write, read back over CIP so the result is the controller's answer. */
+async function write(spec) {
+  return await connectAndRun(spec, async (plc) => {
+    const entry = spec.tag
+    const tag = new ethernetIp.Tag(entry.name, entry.program)
+    // Read first: the driver needs the controller's own type to encode the write.
+    await plc.readTag(tag)
+    const before = tag.value
+    const actualType = tag.type
+    tag.value = spec.value
+    await plc.writeTag(tag)
+    await plc.readTag(tag)
+    const readback = tag.value
+    return {
+      tag: addressOf(entry),
+      declared_data_type: entry.data_type,
+      actual_data_type: actualType,
+      previous_value: before,
+      requested_value: spec.value,
+      readback,
+      verified: Object.is(readback, spec.value) || (typeof readback === 'number' && typeof spec.value === 'number' && Math.abs(readback - spec.value) < 1e-6),
+      written_at: new Date().toISOString(),
+    }
+  })
+}
+
+/** Set the wall clock; L8x only, and read back to prove it landed. */
+async function writeClock(spec) {
+  return await connectAndRun(spec, async (plc) => {
+    const target = new Date(spec.iso)
+    if (Number.isNaN(target.getTime())) throw new Error('Invalid wall clock timestamp')
+    await plc.writeWallClock(target)
+    await plc.readWallClock()
+    const readback = plc.properties.time instanceof Date ? plc.properties.time.toISOString() : String(plc.properties.time)
+    return { requested_time: target.toISOString(), readback, verified: Math.abs(Date.parse(readback) - target.getTime()) < 2000 }
+  })
+}
+
+/** UDP broadcast discovery: where are the controllers on this LAN. */
+async function discover(spec) {
+  const browser = new ethernetIp.Browser()
+  const devices = new Map()
+  browser.on('Device List Updated', list => {
+    for (const device of list) {
+      const address = device?.socketAddress?.sin_addr
+      if (typeof address === 'string') devices.set(address, device)
+    }
+  })
+  browser.on('error', error => { void error })
+  try {
+    browser.start()
+    await delay(spec.duration)
+  } finally {
+    browser.stop()
+  }
+  return {
+    seconds: spec.duration / 1000,
+    devices: [...devices.entries()].map(([ip, device]) => ({
+      ip_address: ip,
+      product_name: String(device.productName ?? ''),
+      revision: String(device.revision ?? ''),
+      serial_number: String(device.serialNumber ?? ''),
+      vendor_id: Number(device.vendorID ?? 0),
+      device_type: Number(device.deviceType ?? 0),
+      status: Number(device.status ?? 0),
+    })),
+  }
+}
+
+const OPERATIONS = { read, clock, write, 'write-clock': writeClock, discover }
+
+if (!isMainThread) {
+  try {
+    const operation = OPERATIONS[workerData?.op]
+    if (operation === undefined) throw new Error('Unknown CIP worker operation')
+    parentPort.postMessage({ ok: true, value: await operation(workerData) })
+  } catch (error) {
+    parentPort.postMessage({ ok: false, message: error instanceof Error ? error.message : 'Controller transaction failed' })
+  } finally { parentPort.close() }
+}

package/vendor/l5x/lib/core/params.d.ts

@@ -9,7 +9,7 @@
  */
 /** One JSON Schema property, with the description that is mandatory here. */
 export interface ParameterSchema {
-    readonly type: 'string' | 'integer' | 'number' | 'boolean' | 'array' | 'object';
+    readonly type: 'string' | 'integer' | 'number' | 'boolean' | 'array' | 'object' | readonly ('string' | 'integer' | 'number' | 'boolean')[];
     readonly description: string;
     readonly enum?: readonly string[];
     readonly items?: ParameterSchema;
@@ -28,6 +28,8 @@ export declare function string(description: string, extra?: Partial<ParameterSch
 export declare function integer(description: string, extra?: Partial<ParameterSchema>): ParameterSchema;
 /** A string parameter restricted to a known set. */
 export declare function choice(description: string, values: readonly string[], extra?: Partial<ParameterSchema>): ParameterSchema;
+/** A boolean-or-number parameter, for a value whose real type comes from the project. */
+export declare function scalar(description: string, extra?: Partial<ParameterSchema>): ParameterSchema;
 /** An array of one parameter type. */
 export declare function list(description: string, items: ParameterSchema, extra?: Partial<ParameterSchema>): ParameterSchema;
 /** One object element of an array parameter. */

package/vendor/l5x/lib/core/params.js

@@ -19,6 +19,10 @@ export function integer(description, extra = {}) {
 export function choice(description, values, extra = {}) {
     return { type: 'string', description, enum: values, ...extra };
 }
+/** A boolean-or-number parameter, for a value whose real type comes from the project. */
+export function scalar(description, extra = {}) {
+    return { type: ['boolean', 'number'], description, ...extra };
+}
 /** An array of one parameter type. */
 export function list(description, items, extra = {}) {
     return { type: 'array', description, items, ...extra };

package/vendor/l5x/lib/engine/cip-request.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Validation for one-shot controller transactions.
+ *
+ * Nothing here opens a socket. Every argument is resolved against the open
+ * export first, so a mistyped tag, an alias, an array or a type-mismatched write
+ * is refused before the controller is contacted.
+ *
+ * @module dsh-engineering-l5x/engine/cip-request
+ */
+import { type ProjectSnapshot } from '../session.ts';
+import type { PollingConfig } from './direct-polling.ts';
+/** Scalar types this surface can read and write. */
+declare const SCALARS: readonly ["BOOL", "INT", "DINT", "REAL"];
+type Scalar = (typeof SCALARS)[number];
+/** One resolved scalar address. */
+export interface ScalarTag {
+    name: string;
+    program?: string;
+    data_type: Scalar;
+}
+/**
+ * Resolve the controller address and slot both read and write share.
+ * @param input - Tool arguments.
+ * @param config - Resolved deployment limits.
+ * @returns The validated target.
+ */
+export declare function controllerTarget(input: Readonly<Record<string, unknown>>, config: PollingConfig): {
+    ip: string;
+    slot: number;
+    timeout: number;
+};
+/**
+ * Resolve declared scalar tags for a batch read, then bound the batch.
+ * @param project - Fresh export snapshot.
+ * @param input - Tool arguments carrying `tags`.
+ * @param config - Resolved deployment limits.
+ * @param maxBatch - Largest accepted batch.
+ * @returns Worker request and operand evidence.
+ */
+export declare function batchReadRequest(project: ProjectSnapshot, input: Readonly<Record<string, unknown>>, config: PollingConfig, maxBatch: number): {
+    request: {
+        tags: ScalarTag[];
+        ip: string;
+        slot: number;
+        timeout: number;
+        op: string;
+    };
+    evidence: {
+        tag: string;
+        scope: string;
+        references: import("./analysis.ts").Evidence[];
+        reference_completeness: string;
+    }[];
+};
+/**
+ * Resolve one writable scalar and check the value against its declared type.
+ * @param project - Fresh export snapshot.
+ * @param input - Tool arguments carrying `name`, optional `program`, and `value`.
+ * @param config - Resolved deployment limits.
+ * @returns The validated worker request.
+ */
+export declare function writableTagRequest(project: ProjectSnapshot, input: Readonly<Record<string, unknown>>, config: PollingConfig): {
+    request: {
+        tag: ScalarTag;
+        value: number | boolean;
+        ip: string;
+        slot: number;
+        timeout: number;
+        op: string;
+    };
+};
+/**
+ * Bound a discovery window.
+ * @param input - Tool arguments carrying optional `duration_seconds`.
+ * @param config - Resolved deployment limits.
+ * @returns Worker request with the window in milliseconds.
+ */
+export declare function discoverRequest(input: Readonly<Record<string, unknown>>, config: PollingConfig): {
+    request: {
+        op: string;
+        duration: number;
+        timeout: number;
+    };
+};
+export {};

package/vendor/l5x/lib/engine/cip-request.js

@@ -0,0 +1,134 @@
+/**
+ * Validation for one-shot controller transactions.
+ *
+ * Nothing here opens a socket. Every argument is resolved against the open
+ * export first, so a mistyped tag, an alias, an array or a type-mismatched write
+ * is refused before the controller is contacted.
+ *
+ * @module dsh-engineering-l5x/engine/cip-request
+ */
+import { isIPv4 } from 'node:net';
+import { EngineeringError } from "../session.js";
+import { aliasesOf } from "./configuration.js";
+import { findReferences } from "./analysis.js";
+import { controllerElementOf } from "../model/parse.js";
+import { elementChildren, firstChild } from "../model/xml.js";
+/** Scalar types this surface can read and write. */
+const SCALARS = ['BOOL', 'INT', 'DINT', 'REAL'];
+/** Integer ranges enforced before a write leaves the machine. */
+const RANGES = { INT: [-32768, 32767], DINT: [-2147483648, 2147483647] };
+const isScalar = (value) => typeof value === 'string' && SCALARS.includes(value);
+/**
+ * Resolve the controller address and slot both read and write share.
+ * @param input - Tool arguments.
+ * @param config - Resolved deployment limits.
+ * @returns The validated target.
+ */
+export function controllerTarget(input, config) {
+    if (!config.enabled)
+        throw new EngineeringError('DIRECT_POLLING_DISABLED', 'Enable directPollingEnabled to use SDK-independent reads');
+    const ip = input.ip_address;
+    if (typeof ip !== 'string' || !isIPv4(ip) || (config.allowedAddresses.length > 0 && !config.allowedAddresses.includes(ip)))
+        throw new EngineeringError('INVALID_CONTROLLER', 'Select an explicit IPv4 address allowed by this profile');
+    const slot = input.slot ?? 0;
+    if (typeof slot !== 'number' || !Number.isInteger(slot) || slot < 0 || slot > 31)
+        throw new EngineeringError('INVALID_POLL', 'slot must be an integer between 0 and 31');
+    return { ip, slot, timeout: config.requestTimeoutMs };
+}
+/**
+ * Resolve declared scalar tags for a batch read, then bound the batch.
+ * @param project - Fresh export snapshot.
+ * @param input - Tool arguments carrying `tags`.
+ * @param config - Resolved deployment limits.
+ * @param maxBatch - Largest accepted batch.
+ * @returns Worker request and operand evidence.
+ */
+export function batchReadRequest(project, input, config, maxBatch) {
+    const target = controllerTarget(input, config);
+    const raw = typeof input.tags_json === 'string' ? JSON.parse(input.tags_json) : null;
+    if (!Array.isArray(raw) || raw.length < 1 || raw.length > maxBatch)
+        throw new EngineeringError('INVALID_POLL', `tags must contain 1 through ${String(maxBatch)} declared scalar tags`);
+    const tags = raw.map((entry) => resolveScalar(project, entry));
+    const seen = new Set();
+    for (const tag of tags) {
+        const key = `${tag.program ?? 'controller'}::${tag.name}`.toLowerCase();
+        if (seen.has(key))
+            throw new EngineeringError('INVALID_POLL', 'Duplicate tag in the batch');
+        seen.add(key);
+    }
+    return {
+        request: { op: 'read', ...target, tags },
+        evidence: tags.map(tag => ({
+            tag: tag.name,
+            scope: tag.program ?? 'controller',
+            references: findReferences(project, tag.name)
+                .filter(reference => reference.resolved?.toLowerCase() === `${tag.program ?? 'controller'}::${tag.name}`.toLowerCase()),
+            reference_completeness: 'static_partial',
+        })),
+    };
+}
+/**
+ * Resolve one writable scalar and check the value against its declared type.
+ * @param project - Fresh export snapshot.
+ * @param input - Tool arguments carrying `name`, optional `program`, and `value`.
+ * @param config - Resolved deployment limits.
+ * @returns The validated worker request.
+ */
+export function writableTagRequest(project, input, config) {
+    const target = controllerTarget(input, config);
+    const name = input.name;
+    const program = input.program;
+    const tag = resolveScalar(project, { name, ...(program === undefined ? {} : { scope: program }) });
+    const value = input.value;
+    if (tag.data_type === 'BOOL') {
+        if (typeof value !== 'boolean')
+            throw new EngineeringError('INVALID_WRITE', `${tag.name} is BOOL; value must be true or false`, 'Pass value: true or value: false.');
+    }
+    else if (typeof value !== 'number' || !Number.isFinite(value)) {
+        throw new EngineeringError('INVALID_WRITE', `${tag.name} is ${tag.data_type}; value must be a finite number`, 'Pass a number for INT, DINT or REAL.');
+    }
+    else if (tag.data_type !== 'REAL') {
+        const [min, max] = RANGES[tag.data_type];
+        if (!Number.isInteger(value) || value < min || value > max)
+            throw new EngineeringError('INVALID_WRITE', `${tag.name} is ${tag.data_type}; value must be an integer between ${String(min)} and ${String(max)}`, 'Use whole numbers inside the declared range.');
+    }
+    return { request: { op: 'write', ...target, tag, value } };
+}
+/**
+ * Bound a discovery window.
+ * @param input - Tool arguments carrying optional `duration_seconds`.
+ * @param config - Resolved deployment limits.
+ * @returns Worker request with the window in milliseconds.
+ */
+export function discoverRequest(input, config) {
+    if (!config.enabled)
+        throw new EngineeringError('DIRECT_POLLING_DISABLED', 'Enable directPollingEnabled to use controller discovery');
+    const seconds = input.duration_seconds ?? 3;
+    if (typeof seconds !== 'number' || !Number.isInteger(seconds) || seconds < 1 || seconds > 15)
+        throw new EngineeringError('INVALID_POLL', 'duration_seconds must be an integer between 1 and 15');
+    return { request: { op: 'discover', duration: seconds * 1000, timeout: config.requestTimeoutMs } };
+}
+/** Resolve one declared scalar (never an alias, array or unknown tag). */
+function resolveScalar(project, entry) {
+    if (!entry || typeof entry !== 'object' || !('name' in entry) || typeof entry.name !== 'string'
+        || !/^[A-Za-z_][A-Za-z0-9_]*$/u.test(entry.name)
+        || !Object.keys(entry).every(key => key === 'name' || key === 'scope'))
+        throw new EngineeringError('UNSUPPORTED_WRITE_TAG', 'Each tag needs an exact scalar name and optional scope only');
+    const scope = 'scope' in entry ? entry.scope : 'controller';
+    if (typeof scope !== 'string' || (scope !== 'controller' && !/^[A-Za-z_][A-Za-z0-9_]*$/u.test(scope)))
+        throw new EngineeringError('INVALID_POLL', 'scope must be controller or an exact program name');
+    const declared = project.document.tags.find(tag => tag.name === entry.name && tag.scope === scope);
+    const controller = controllerElementOf(project.document);
+    const programs = firstChild(controller, 'Programs');
+    const container = scope === 'controller' ? controller : programs === undefined ? undefined
+        : elementChildren(programs, 'Program').find(program => program.attrs.Name === scope);
+    const tagContainer = container === undefined ? undefined : firstChild(container, 'Tags');
+    const declaration = tagContainer === undefined ? undefined : elementChildren(tagContainer, 'Tag').find(tag => tag.attrs.Name === entry.name);
+    const dimensions = declaration?.attrs.Dimensions ?? declaration?.attrs.Dimension ?? '';
+    if (!declared || aliasesOf(project.document).has(`${scope}::${declared.name}`)
+        || !isScalar(declared.dataType)
+        || (dimensions !== '' && dimensions !== '0')
+        || declaration?.attrs.ExternalAccess === 'None')
+        throw new EngineeringError('UNSUPPORTED_WRITE_TAG', `${String(entry.name)} is not a writable declared scalar BOOL, INT, DINT or REAL`, 'Reads accept the same tags; writes additionally need ExternalAccess and no array dimensions.');
+    return { name: declared.name, ...(scope === 'controller' ? {} : { program: scope }), data_type: declared.dataType };
+}

package/vendor/l5x/lib/engine/cip-transaction.d.ts

@@ -0,0 +1,115 @@
+/**
+ * One-shot EtherNet/IP transactions: batch reads, identity/clock, writes and
+ * discovery, each in its own worker so a hung socket cannot hold the host.
+ *
+ * Reads are the normal case. Writes are only ever reached through a tool that
+ * has already asked a human for this exact operation, and every write result is
+ * the readback the controller returned, never an assumption that it worked.
+ *
+ * @module dsh-engineering-l5x/engine/cip-transaction
+ */
+/** One observed value from a batch read. */
+export interface CipValue {
+    tag: string;
+    data_type: string;
+    actual_data_type?: string;
+    value: boolean | number | null;
+    quality: 'good' | 'bad';
+    observed_at: string;
+    error?: string;
+}
+/** Controller identity as CIP reports it. */
+export interface CipIdentity {
+    product_name: string;
+    serial_number: number;
+    revision: string;
+    status: number;
+}
+/** Result of the batch read. */
+export interface CipReadResult {
+    controller: CipIdentity;
+    request_count: number;
+    observed_at: string;
+    values: CipValue[];
+}
+/** Result of the clock read. */
+export interface CipClockResult {
+    controller: CipIdentity;
+    supported: boolean;
+    controller_time?: string;
+    host_time: string;
+    reason?: string;
+}
+/** Result of one tag write. */
+export interface CipWriteResult {
+    tag: string;
+    declared_data_type: string;
+    actual_data_type?: string;
+    previous_value: boolean | number | null;
+    requested_value: boolean | number;
+    readback: boolean | number | null;
+    verified: boolean;
+    written_at: string;
+}
+/** Result of a wall-clock write. */
+export interface CipWriteClockResult {
+    requested_time: string;
+    readback: string;
+    verified: boolean;
+}
+/** One discovered device. */
+export interface CipDevice {
+    ip_address: string;
+    product_name: string;
+    revision: string;
+    serial_number: string;
+    vendor_id: number;
+    device_type: number;
+    status: number;
+}
+/** Result of discovery. */
+export interface CipDiscoverResult {
+    seconds: number;
+    devices: CipDevice[];
+}
+/** Validate a batch-read result. */
+export declare function decodeReadResult(value: unknown): CipReadResult;
+/** Validate a clock result. */
+export declare function decodeClockResult(value: unknown): CipClockResult;
+/** Validate a write result. */
+export declare function decodeWriteResult(value: unknown): CipWriteResult;
+/** Validate a wall-clock write result. */
+export declare function decodeWriteClockResult(value: unknown): CipWriteClockResult;
+/** Validate a discovery result. */
+export declare function decodeDiscoverResult(value: unknown): CipDiscoverResult;
+/** Bounds shared with the polling engine. */
+export interface TransactionLimits {
+    /** Per-request driver timeout, in milliseconds. */
+    timeout: number;
+    /** Most simultaneous transactions. */
+    maxConcurrent: number;
+}
+/**
+ * Run one worker transaction and enforce its deadline.
+ *
+ * The worker emits exactly one message: `{ ok: true, value }` or
+ * `{ ok: false, message }`. Anything else, or a worker that outlives the
+ * deadline, fails the call rather than returning a partial answer.
+ */
+export declare class CipTransactions {
+    private readonly workerPath;
+    private readonly limits;
+    private active;
+    private disposed;
+    constructor(workerPath: string, limits: TransactionLimits);
+    /**
+     * Run one operation.
+     * @param spec - Worker request, already validated by the caller.
+     * @param signal - Optional lifetime, aborted by the calling turn.
+     * @param extraMs - Deadline beyond the driver timeout (discovery needs its window).
+     * @returns The raw `value` of the worker's reply.
+     */
+    run(spec: Readonly<Record<string, unknown>>, signal?: AbortSignal, extraMs?: number): Promise<unknown>;
+    /** Refuse new work and let running transactions finish. */
+    dispose(): Promise<void>;
+}

package/vendor/l5x/lib/engine/cip-transaction.js

@@ -0,0 +1,185 @@
+/**
+ * One-shot EtherNet/IP transactions: batch reads, identity/clock, writes and
+ * discovery, each in its own worker so a hung socket cannot hold the host.
+ *
+ * Reads are the normal case. Writes are only ever reached through a tool that
+ * has already asked a human for this exact operation, and every write result is
+ * the readback the controller returned, never an assumption that it worked.
+ *
+ * @module dsh-engineering-l5x/engine/cip-transaction
+ */
+import { Worker } from 'node:worker_threads';
+import { EngineeringError } from "../session.js";
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const isText = (value) => typeof value === 'string';
+const isInteger = (value) => typeof value === 'number' && Number.isInteger(value);
+const isFiniteNumber = (value) => typeof value === 'number' && Number.isFinite(value);
+const isScalar = (value) => typeof value === 'boolean' || isFiniteNumber(value);
+/** Narrow one identity record. */
+function identityOf(value) {
+    if (!isRecord(value) || !isText(value.product_name) || !isInteger(value.serial_number)
+        || !isText(value.revision) || !isFiniteNumber(value.status))
+        throw new Error('Invalid controller identity in CIP result');
+    return { product_name: value.product_name, serial_number: value.serial_number, revision: value.revision, status: value.status };
+}
+/** Narrow one observed value. */
+function valueOf(value) {
+    if (!isRecord(value) || !isText(value.tag) || !isText(value.data_type) || !isText(value.observed_at)
+        || !(value.value === null || isScalar(value.value)) || (value.quality !== 'good' && value.quality !== 'bad'))
+        throw new Error('Invalid CIP read value');
+    return {
+        tag: value.tag,
+        data_type: value.data_type,
+        ...(isText(value.actual_data_type) ? { actual_data_type: value.actual_data_type } : {}),
+        value: value.value,
+        quality: value.quality,
+        observed_at: value.observed_at,
+        ...(isText(value.error) ? { error: value.error.slice(0, 1000) } : {}),
+    };
+}
+/** Validate a batch-read result. */
+export function decodeReadResult(value) {
+    if (!isRecord(value) || !isInteger(value.request_count) || !isText(value.observed_at)
+        || !Array.isArray(value.values) || value.values.length > 256)
+        throw new Error('Invalid CIP read result');
+    return {
+        controller: identityOf(value.controller),
+        request_count: value.request_count,
+        observed_at: value.observed_at,
+        values: value.values.map(valueOf),
+    };
+}
+/** Validate a clock result. */
+export function decodeClockResult(value) {
+    if (!isRecord(value) || typeof value.supported !== 'boolean' || !isText(value.host_time))
+        throw new Error('Invalid CIP clock result');
+    return {
+        controller: identityOf(value.controller),
+        supported: value.supported,
+        host_time: value.host_time,
+        ...(isText(value.controller_time) ? { controller_time: value.controller_time } : {}),
+        ...(isText(value.reason) ? { reason: value.reason.slice(0, 500) } : {}),
+    };
+}
+/** Validate a write result. */
+export function decodeWriteResult(value) {
+    if (!isRecord(value) || !isText(value.tag) || !isText(value.declared_data_type) || !isText(value.written_at)
+        || !(value.previous_value === null || isScalar(value.previous_value))
+        || !isScalar(value.requested_value) || !(value.readback === null || isScalar(value.readback))
+        || typeof value.verified !== 'boolean')
+        throw new Error('Invalid CIP write result');
+    return {
+        tag: value.tag,
+        declared_data_type: value.declared_data_type,
+        ...(isText(value.actual_data_type) ? { actual_data_type: value.actual_data_type } : {}),
+        previous_value: value.previous_value,
+        requested_value: value.requested_value,
+        readback: value.readback,
+        verified: value.verified,
+        written_at: value.written_at,
+    };
+}
+/** Validate a wall-clock write result. */
+export function decodeWriteClockResult(value) {
+    if (!isRecord(value) || !isText(value.requested_time) || !isText(value.readback) || typeof value.verified !== 'boolean')
+        throw new Error('Invalid CIP clock write result');
+    return { requested_time: value.requested_time, readback: value.readback, verified: value.verified };
+}
+/** Validate a discovery result. */
+export function decodeDiscoverResult(value) {
+    if (!isRecord(value) || !isFiniteNumber(value.seconds) || !Array.isArray(value.devices) || value.devices.length > 512)
+        throw new Error('Invalid CIP discovery result');
+    return {
+        seconds: value.seconds,
+        devices: value.devices.map((device) => {
+            if (!isRecord(device) || !isText(device.ip_address) || !isText(device.product_name) || !isText(device.revision)
+                || !isText(device.serial_number) || !isFiniteNumber(device.vendor_id) || !isFiniteNumber(device.device_type)
+                || !isFiniteNumber(device.status))
+                throw new Error('Invalid discovered device');
+            return {
+                ip_address: device.ip_address,
+                product_name: device.product_name,
+                revision: device.revision,
+                serial_number: device.serial_number,
+                vendor_id: device.vendor_id,
+                device_type: device.device_type,
+                status: device.status,
+            };
+        }),
+    };
+}
+/**
+ * Run one worker transaction and enforce its deadline.
+ *
+ * The worker emits exactly one message: `{ ok: true, value }` or
+ * `{ ok: false, message }`. Anything else, or a worker that outlives the
+ * deadline, fails the call rather than returning a partial answer.
+ */
+export class CipTransactions {
+    workerPath;
+    limits;
+    active = 0;
+    disposed = false;
+    constructor(workerPath, limits) {
+        this.workerPath = workerPath;
+        this.limits = limits;
+    }
+    /**
+     * Run one operation.
+     * @param spec - Worker request, already validated by the caller.
+     * @param signal - Optional lifetime, aborted by the calling turn.
+     * @param extraMs - Deadline beyond the driver timeout (discovery needs its window).
+     * @returns The raw `value` of the worker's reply.
+     */
+    async run(spec, signal, extraMs = 0) {
+        if (this.disposed)
+            throw new EngineeringError('CONTROLLER_BUSY', 'The controller bridge is shutting down');
+        if (this.active >= this.limits.maxConcurrent)
+            throw new EngineeringError('CONTROLLER_BUSY', 'Controller transaction capacity is occupied');
+        signal?.throwIfAborted();
+        this.active += 1;
+        const worker = new Worker(this.workerPath, { workerData: spec, env: {}, stdout: true, stderr: true });
+        worker.stdout.resume();
+        worker.stderr.resume();
+        const deadline = this.limits.timeout + extraMs;
+        const timer = setTimeout(() => { void worker.terminate(); }, deadline);
+        const onAbort = () => { void worker.terminate(); };
+        signal?.addEventListener('abort', onAbort, { once: true });
+        try {
+            return await new Promise((resolve, reject) => {
+                let settled = false;
+                const settle = (fn) => { if (!settled) {
+                    settled = true;
+                    fn();
+                } };
+                worker.on('message', (message) => {
+                    if (!isRecord(message))
+                        return settle(() => reject(new Error('Malformed controller reply')));
+                    if (message.ok === true)
+                        return settle(() => resolve(message.value));
+                    settle(() => reject(new Error(isText(message.message) ? message.message : 'Controller transaction failed')));
+                });
+                worker.once('error', error => settle(() => reject(error)));
+                worker.once('exit', code => {
+                    settle(() => reject(new Error(`Controller transaction ended without a reply (exit ${String(code)})`)));
+                });
+            });
+        }
+        catch (error) {
+            if (signal?.aborted)
+                throw new EngineeringError('CONTROLLER_CANCELLED', 'The controller transaction was cancelled');
+            throw error instanceof EngineeringError ? error : new EngineeringError('CONTROLLER_UNREACHABLE', error instanceof Error ? error.message : 'Controller transaction failed', 'Check the controller address and slot, that the port is reachable, and retry.');
+        }
+        finally {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+            this.active -= 1;
+            void worker.terminate();
+        }
+    }
+    /** Refuse new work and let running transactions finish. */
+    async dispose() {
+        this.disposed = true;
+        this.active = 0;
+    }
+}

package/vendor/l5x/lib/live.d.ts

@@ -32,6 +32,10 @@ export interface Config {
     maxConcurrent?: number;
     /** Optional IPv4 allowlist; empty permits any explicit address. */
     allowedAddresses?: string[];
+    /** Permit one-shot writes (tag and wall clock). Each write still needs human approval. Defaults to false. */
+    allowWrites?: boolean;
+    /** Largest accepted batch read. Defaults to 64. */
+    maxBatchTags?: number;
     /** Chart redraw interval, independent of reads. Defaults to 250 ms. */
     displayRefreshMs?: number;
     /** Most points retained per chart. Defaults to 1200. */
@@ -45,4 +49,5 @@ export interface Config {
  */
 export declare function apply(ctx: PluginContext, config?: Config): void;
 export { DirectPolling } from './engine/direct-polling.ts';
+export { CipTransactions } from './engine/cip-transaction.ts';
 export { liveTools } from './tools/live.ts';

package/vendor/l5x/lib/live.js

@@ -9,6 +9,7 @@
  */
 import { fileURLToPath } from 'node:url';
 import { DirectPolling } from "./engine/direct-polling.js";
+import { CipTransactions } from "./engine/cip-transaction.js";
 import { liveTools } from "./tools/live.js";
 import { PROJECTS_SERVICE } from "./index.js";
 /** Plugin name in a composition. */
@@ -39,10 +40,20 @@ export function apply(ctx, config = {}) {
         displayRefreshMs: config.displayRefreshMs ?? 250,
         displayMaxSamples: config.displayMaxSamples ?? 1200,
     });
+    const transactions = new CipTransactions(fileURLToPath(new URL('../cip-worker.mjs', import.meta.url)), {
+        timeout: config.requestTimeoutMs ?? 3000,
+        maxConcurrent: config.maxConcurrent ?? 2,
+    });
     const effect = ctx.effect;
-    effect?.(() => () => { void polling.dispose(); });
-    for (const definition of liveTools(session, polling, ctx))
+    effect?.(() => () => { void polling.dispose(); void transactions.dispose(); });
+    const extensions = {
+        transactions,
+        allowWrites: config.allowWrites === true,
+        maxBatchTags: config.maxBatchTags ?? 64,
+    };
+    for (const definition of liveTools(session, polling, ctx, extensions))
         ctx.tools.register(definition);
 }
 export { DirectPolling } from "./engine/direct-polling.js";
+export { CipTransactions } from "./engine/cip-transaction.js";
 export { liveTools } from "./tools/live.js";

package/vendor/l5x/lib/tools/live.d.ts

@@ -1,21 +1,32 @@
 /**
- * SDK-free live reads over EtherNet/IP.
+ * SDK-free EtherNet/IP surface: reads, identity, discovery and the two
+ * approval-gated writes.
  *
- * Two tools: a bounded foreground poll, and a session-owned trend job the chart
- * can follow without a model call per sample. Both read declared scalar tags,
- * never write, and state that live logic is not the exported logic.
+ * Reads never change the controller and need no approval. Writes do: a write is
+ * refused unless the row's config allows writes AND a human approves that exact
+ * operation, and its result is the value read back over CIP, not an assumption.
  *
  * @module dsh-engineering-l5x/tools/live
  */
 import type { PluginContext, ToolDefinition } from '../core/tool.ts';
 import type { ProjectSession } from '../session.ts';
 import { type DirectPolling } from '../engine/direct-polling.ts';
+import { type CipTransactions } from '../engine/cip-transaction.ts';
+/** Extra capabilities the live entry mounts beside polling. */
+export interface LiveExtensions {
+    readonly transactions: CipTransactions;
+    /** Writes are refused unless the row config enables them. */
+    readonly allowWrites: boolean;
+    /** Largest accepted batch read. */
+    readonly maxBatchTags: number;
+}
 /**
  * The live tools.
  *
  * @param session - Project handles for the calling chat.
  * @param polling - The polling engine and its configuration.
- * @param ctx - Plugin context that may provide the job service.
+ * @param ctx - Plugin context that may provide the job and approval services.
+ * @param extensions - One-shot transactions and the write switch.
  * @returns Tool definitions in registration order.
  */
-export declare function liveTools(session: ProjectSession, polling: DirectPolling, ctx: PluginContext): readonly ToolDefinition[];
+export declare function liveTools(session: ProjectSession, polling: DirectPolling, ctx: PluginContext, extensions: LiveExtensions): readonly ToolDefinition[];

package/vendor/l5x/lib/tools/live.js

@@ -1,16 +1,20 @@
 /**
- * SDK-free live reads over EtherNet/IP.
+ * SDK-free EtherNet/IP surface: reads, identity, discovery and the two
+ * approval-gated writes.
  *
- * Two tools: a bounded foreground poll, and a session-owned trend job the chart
- * can follow without a model call per sample. Both read declared scalar tags,
- * never write, and state that live logic is not the exported logic.
+ * Reads never change the controller and need no approval. Writes do: a write is
+ * refused unless the row's config allows writes AND a human approves that exact
+ * operation, and its result is the value read back over CIP, not an assumption.
  *
  * @module dsh-engineering-l5x/tools/live
  */
 import { success } from "../core/result.js";
-import { integer, list, object, objectItem, string } from "../core/params.js";
+import { integer, list, object, objectItem, scalar, string } from "../core/params.js";
 import { pollingRequest } from "../engine/direct-polling.js";
+import { batchReadRequest, controllerTarget, discoverRequest, writableTagRequest } from "../engine/cip-request.js";
+import { decodeClockResult, decodeDiscoverResult, decodeReadResult, decodeWriteClockResult, decodeWriteResult, } from "../engine/cip-transaction.js";
 import { L5xError } from "../core/errors.js";
+import { requireHumanApproval } from "../approvals.js";
 import { PROJECT_ID, optionalInteger, optionalString, requiredString, tool } from "./common.js";
 /** A direct read is not a guarantee about the scan. */
 const LIVE_COVERAGE = {
@@ -21,6 +25,15 @@ const LIVE_COVERAGE = {
         'transitions between sweeps',
     ],
 };
+/** A verified write is a fact about the tag, not about the machine. */
+const WRITE_COVERAGE = {
+    complete: false,
+    unverified: [
+        'that the written value is the intended process change',
+        'that the logic reacts as expected on the next scan',
+        'that the value is still in place after the next scan',
+    ],
+};
 /** The tags argument, as flat objects rather than a JSON string. */
 function tagsOf(args) {
     const raw = args.tags;
@@ -41,28 +54,34 @@ function tagsOf(args) {
     });
     return JSON.stringify(tags);
 }
-/** The same tag parameter for both tools. */
+/** The same tag parameter for the polling tools. */
 const TAGS_PARAM = list('Controller-scoped scalar tags to read, 1 to 16. Each entry names the tag and optionally its program.', objectItem('One declared scalar tag.', {
     name: string('Tag name. Example: "LineSpeed".'),
     program: string('Program scope for a program-scoped tag. Omit for a controller tag.'),
 }, ['name']), { minItems: 1, maxItems: 16 });
+/** The controller address shared by every non-discovery call. */
+const target = {
+    ip_address: string('Controller IPv4 address the human named. Example: "192.168.1.10".'),
+    slot: integer('CPU slot, 0 to 31. Default 0.', { minimum: 0, maximum: 31, default: 0 }),
+};
 /**
  * The live tools.
  *
  * @param session - Project handles for the calling chat.
  * @param polling - The polling engine and its configuration.
- * @param ctx - Plugin context that may provide the job service.
+ * @param ctx - Plugin context that may provide the job and approval services.
+ * @param extensions - One-shot transactions and the write switch.
  * @returns Tool definitions in registration order.
  */
-export function liveTools(session, polling, ctx) {
+export function liveTools(session, polling, ctx, extensions) {
+    const { transactions } = extensions;
     return [
         tool({
             name: 'poll_live_tags',
             description: 'Read declared scalar PLC tags directly over EtherNet/IP without Studio, FactoryTalk Linx, an ACD upload or the SDK. Explicit controller IPv4 and slot required. Returns timestamped sweeps, quality and controller identity; no writes.',
             parameters: object({
                 project_id: PROJECT_ID,
-                ip_address: string('Controller IPv4 address the human named. Example: "192.168.1.10".'),
-                slot: integer('CPU slot, 0 to 31. Default 0.', { minimum: 0, maximum: 31, default: 0 }),
+                ...target,
                 tags: TAGS_PARAM,
                 sample_count: integer('Number of sweeps to read. Default 1.', { minimum: 1, maximum: 1200, default: 1 }),
                 interval_ms: integer('Requested interval between sweeps. Default 200.', { minimum: 50, maximum: 600000, default: 200 }),
@@ -78,7 +97,7 @@ export function liveTools(session, polling, ctx) {
                 }, polling.config);
                 const frames = await polling.start(request, () => { }, exec.signal).done;
                 await session.require(project.id, exec);
-                return success(`Read ${request.samples} sweep(s) from ${request.ip}.`, {
+                return success(`Read ${String(request.samples)} sweep(s) from ${request.ip}.`, {
                     project_id: project.id,
                     source_sha256: project.sha256,
                     ip_address: request.ip,
@@ -95,13 +114,156 @@ export function liveTools(session, polling, ctx) {
                 }, [], LIVE_COVERAGE);
             },
         }),
+        tool({
+            name: 'read_live_tags',
+            description: 'Read up to 64 declared scalar tags in ONE EtherNet/IP request (CIP tag group). Faster than polling for a one-shot snapshot; no writes, no Studio, no Linx, no SDK.',
+            parameters: object({
+                project_id: PROJECT_ID,
+                ...target,
+                tags: list('Declared scalar tags to read together, 1 to 64. Each entry names the tag and optionally its program.', objectItem('One declared scalar tag.', {
+                    name: string('Tag name. Example: "LineSpeed".'),
+                    program: string('Program scope for a program-scoped tag. Omit for a controller tag.'),
+                }, ['name']), { minItems: 1, maxItems: 64 }),
+            }, ['ip_address', 'tags']),
+            async run(args, exec) {
+                const project = await session.require(optionalString(args, 'project_id'), exec);
+                const { request, evidence } = batchReadRequest(project, {
+                    ip_address: requiredString(args, 'ip_address'),
+                    slot: optionalInteger(args, 'slot') ?? 0,
+                    tags_json: tagsOf(args),
+                }, polling.config, extensions.maxBatchTags);
+                const result = decodeReadResult(await transactions.run(request, exec.signal));
+                await session.require(project.id, exec);
+                return success(`Read ${String(result.values.length)} tag(s) from ${request.ip} in one request.`, {
+                    project_id: project.id,
+                    source_sha256: project.sha256,
+                    ip_address: request.ip,
+                    slot: request.slot,
+                    provider: 'ethernet-ip',
+                    request_count: result.request_count,
+                    controller: result.controller,
+                    values: result.values,
+                    evidence,
+                    live_logic_matches_export: 'unverified',
+                }, [], LIVE_COVERAGE);
+            },
+        }),
+        tool({
+            name: 'read_controller_clock',
+            description: 'Read controller identity and, on L8x controllers, the wall clock beside the workstation clock. Reports unsupported instead of guessing on other models. No writes.',
+            parameters: object({ ...target }, ['ip_address']),
+            async run(args, exec) {
+                const request = { op: 'clock', ...controllerTarget(args, polling.config) };
+                const result = decodeClockResult(await transactions.run(request, exec.signal));
+                const drift = result.supported && result.controller_time !== undefined
+                    ? Date.parse(result.host_time) - Date.parse(result.controller_time)
+                    : undefined;
+                return success(result.supported
+                    ? `Controller clock ${String(result.controller_time)}; workstation ${result.host_time}.`
+                    : `Controller identity read; wall clock is unavailable on ${result.controller.product_name}.`, {
+                    ip_address: request.ip,
+                    slot: request.slot,
+                    provider: 'ethernet-ip',
+                    controller: result.controller,
+                    clock_supported: result.supported,
+                    ...(result.controller_time === undefined ? {} : { controller_time: result.controller_time }),
+                    host_time: result.host_time,
+                    ...(drift === undefined ? {} : { clock_offset_ms: drift }),
+                    ...(result.reason === undefined ? {} : { reason: result.reason }),
+                }, [], LIVE_COVERAGE);
+            },
+        }),
+        tool({
+            name: 'discover_controllers',
+            description: 'Discover EtherNet/IP controllers on this LAN by UDP broadcast for a bounded window: address, product, revision, serial, status. No address needed, no writes, no Studio or Linx.',
+            parameters: object({
+                duration_seconds: integer('How long to listen for replies, 1 to 15. Default 3.', { minimum: 1, maximum: 15, default: 3 }),
+            }),
+            async run(args, exec) {
+                const { request } = discoverRequest({ duration_seconds: optionalInteger(args, 'duration_seconds') ?? 3 }, polling.config);
+                const result = decodeDiscoverResult(await transactions.run(request, exec.signal, request.duration + 2000));
+                return success(`Found ${String(result.devices.length)} controller(s) in ${String(result.seconds)} s.`, {
+                    provider: 'ethernet-ip',
+                    broadcast_seconds: result.seconds,
+                    devices: result.devices,
+                    limitation: 'Broadcast discovery only reaches devices that answer on this subnet; a routed or filtered network returns nothing.',
+                }, [], { complete: false, unverified: ['that a silent device is absent', 'that a listed device is reachable for tag reads'] });
+            },
+        }),
+        tool({
+            name: 'write_live_tag',
+            description: 'Write ONE declared scalar PLC tag over EtherNet/IP, then read it back and report the controller\'s own value. Requires the row\'s writes switch AND human approval for this exact write. Destructive: it changes a running machine.',
+            parameters: object({
+                project_id: PROJECT_ID,
+                ...target,
+                name: string('Declared scalar tag name. Example: "LineSpeed".'),
+                program: string('Program scope for a program-scoped tag. Omit for a controller tag.'),
+                value: scalar('Value to write: true or false for BOOL, a number for INT, DINT or REAL.'),
+            }, ['ip_address', 'name', 'value']),
+            async run(args, exec) {
+                if (!extensions.allowWrites) {
+                    throw new L5xError('WRITES_DISABLED', 'Live writes are switched off for this bundle row.', 'Turn on "allowWrites" in the L5X row configuration on the Plugins page, then request the write again.');
+                }
+                const project = await session.require(optionalString(args, 'project_id'), exec);
+                const { request } = writableTagRequest(project, {
+                    ip_address: requiredString(args, 'ip_address'),
+                    slot: optionalInteger(args, 'slot') ?? 0,
+                    name: requiredString(args, 'name'),
+                    ...(optionalString(args, 'program') === undefined ? {} : { program: optionalString(args, 'program') }),
+                    value: args.value,
+                }, polling.config);
+                const address = request.tag.program === undefined
+                    ? request.tag.name
+                    : `Program:${String(request.tag.program)}.${String(request.tag.name)}`;
+                await requireHumanApproval(ctx, exec, 'write_live_tag', `Write ${JSON.stringify(args.value)} to ${address} on controller ${request.ip} slot ${String(request.slot)}. This changes a running machine.`);
+                const result = decodeWriteResult(await transactions.run(request, exec.signal));
+                await session.require(project.id, exec);
+                if (!result.verified) {
+                    throw new L5xError('WRITE_NOT_VERIFIED', `${result.tag} was written but the readback is ${JSON.stringify(result.readback)}, not ${JSON.stringify(result.requested_value)}.`, 'Inspect the tag in the controller before retrying; a type or scaling mismatch can reject the value.');
+                }
+                return success(`Wrote ${JSON.stringify(result.requested_value)} to ${result.tag}; the controller reads back ${JSON.stringify(result.readback)}.`, {
+                    project_id: project.id,
+                    source_sha256: project.sha256,
+                    ip_address: request.ip,
+                    slot: request.slot,
+                    provider: 'ethernet-ip',
+                    approved: 'allowed-once',
+                    ...result,
+                    live_logic_matches_export: 'unverified',
+                }, [], WRITE_COVERAGE);
+            },
+        }),
+        tool({
+            name: 'write_controller_clock',
+            description: 'Set the controller wall clock (L8x only), then read it back. Requires the row\'s writes switch AND human approval for this exact change.',
+            parameters: object({
+                ...target,
+                time: string('ISO 8601 timestamp to set. Omit to use the workstation clock now. Example: "2026-10-25T09:30:00Z".'),
+            }, ['ip_address']),
+            async run(args, exec) {
+                if (!extensions.allowWrites) {
+                    throw new L5xError('WRITES_DISABLED', 'Live writes are switched off for this bundle row.', 'Turn on "allowWrites" in the L5X row configuration on the Plugins page, then request the change again.');
+                }
+                const request = { op: 'write-clock', ...controllerTarget(args, polling.config), iso: optionalString(args, 'time') ?? new Date().toISOString() };
+                await requireHumanApproval(ctx, exec, 'write_controller_clock', `Set the wall clock of controller ${request.ip} slot ${String(request.slot)} to ${String(request.iso)}.`);
+                const result = decodeWriteClockResult(await transactions.run(request, exec.signal));
+                if (!result.verified) {
+                    throw new L5xError('WRITE_NOT_VERIFIED', `The clock readback ${result.readback} does not match ${result.requested_time}.`, 'Retry once; if it still differs, the controller rejects clock changes (unsupported model or protected).');
+                }
+                return success(`Controller clock set to ${result.readback}.`, {
+                    ip_address: request.ip,
+                    slot: request.slot,
+                    approved: 'allowed-once',
+                    ...result,
+                }, [], WRITE_COVERAGE);
+            },
+        }),
         tool({
             name: 'start_plc_trend',
             description: 'Start a bounded, read-only PLC trend as a session-owned background job. Explicit IPv4, slot and declared scalar tags required. SDK-independent EtherNet/IP; the chart follows the job without a model call per sample.',
             parameters: object({
                 project_id: PROJECT_ID,
-                ip_address: string('Controller IPv4 address the human named. Example: "192.168.1.10".'),
-                slot: integer('CPU slot, 0 to 31. Default 0.', { minimum: 0, maximum: 31, default: 0 }),
+                ...target,
                 tags: TAGS_PARAM,
                 sample_count: integer('Number of sweeps in the trend. Default 300.', { minimum: 1, maximum: 1200, default: 300 }),
                 interval_ms: integer('Requested interval between sweeps. Default 200.', { minimum: 50, maximum: 600000, default: 200 }),
@@ -123,7 +285,7 @@ export function liveTools(session, polling, ctx) {
                 const jobId = jobs.start({
                     kind: 'plc-trend',
                     owner,
-                    label: `PLC trend ${request.ip} slot ${request.slot}`,
+                    label: `PLC trend ${request.ip} slot ${String(request.slot)}`,
                     run(job) {
                         job.append(JSON.stringify({
                             type: 'source',
@@ -157,7 +319,7 @@ export function liveTools(session, polling, ctx) {
                         return { cancel: handle.cancel, done };
                     },
                 });
-                return success(`Trend ${jobId} started for ${request.samples} sweep(s) from ${request.ip}.`, {
+                return success(`Trend ${jobId} started for ${String(request.samples)} sweep(s) from ${request.ip}.`, {
                     job_id: jobId,
                     owner_session_id: owner,
                     project_id: project.id,