@aryacode/dsh-engineering 0.0.0-stage → 0.3.0

package/vendor/l5x/lib/studio-state.js

@@ -0,0 +1,79 @@
+/**
+ * Provenance for ACD exports and verified builds, scoped to one chat.
+ *
+ * An ACD export is only usable as a baseline for a later build when this chat
+ * exported that exact L5X from that exact ACD: both hashes must still match.
+ * The record is what makes that check possible without trusting a path.
+ *
+ * @module dsh-engineering-l5x/studio-state
+ */
+/** Exports and verified builds, scoped to the chat that ran them. */
+export class StudioState {
+    chats = new WeakMap();
+    detached = new Map();
+    buildChats = new WeakMap();
+    detachedBuilds = new Map();
+    /**
+     * Record one export.
+     *
+     * @param exec - Calling context; its chat owns the record.
+     * @param record - Export binding to remember.
+     */
+    record(exec, record) {
+        this.chatsOf(exec).set(record.l5xPath.toLowerCase(), record);
+    }
+    /**
+     * The export that produced one L5X, if this chat produced it.
+     *
+     * @param exec - Calling context.
+     * @param l5xPath - Resolved L5X path.
+     * @returns The export record, or undefined.
+     */
+    forL5x(exec, l5xPath) {
+        return this.chatsOf(exec).get(l5xPath.toLowerCase());
+    }
+    /**
+     * Remember one build that passed and may later be downloaded.
+     *
+     * @param exec - Calling context.
+     * @param id - Verification id returned to the caller.
+     * @param build - Build binding and its review.
+     */
+    addVerified(exec, id, build) {
+        this.buildsOf(exec).set(id, build);
+    }
+    /**
+     * The build behind one verification id, if this chat produced it.
+     *
+     * @param exec - Calling context.
+     * @param id - Verification id.
+     * @returns The verified build, or undefined.
+     */
+    verified(exec, id) {
+        return this.buildsOf(exec).get(id);
+    }
+    /** The record map for one calling chat. */
+    chatsOf(exec) {
+        const chat = exec?.chat;
+        if (chat === undefined)
+            return this.detached;
+        const existing = this.chats.get(chat);
+        if (existing !== undefined)
+            return existing;
+        const created = new Map();
+        this.chats.set(chat, created);
+        return created;
+    }
+    /** The verified-build map for one calling chat. */
+    buildsOf(exec) {
+        const chat = exec?.chat;
+        if (chat === undefined)
+            return this.detachedBuilds;
+        const existing = this.buildChats.get(chat);
+        if (existing !== undefined)
+            return existing;
+        const created = new Map();
+        this.buildChats.set(chat, created);
+        return created;
+    }
+}

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

@@ -0,0 +1,29 @@
+/**
+ * The L5X studio entry: offline SDK work over the read entry's project handles.
+ *
+ * Separate so the SDK's ACD export, build and verification schemas are paid for
+ * only where Studio 5000 is installed and the user opted in. No tool in this
+ * entry contacts a controller.
+ *
+ * @module dsh-engineering-l5x/studio
+ */
+import type { PluginContext } from './core/tool.ts';
+/** Plugin name in a composition. */
+export declare const name = "l5x-studio";
+/** The read entry's project service must already be mounted. */
+export declare const inject: readonly ["tools", "l5xProjects"];
+/** Configuration for the studio entry. */
+export interface Config {
+    /** Largest export, in bytes, one verification may read. Defaults to 64 MiB. */
+    maxFileBytes?: number;
+}
+/**
+ * Register the studio tools.
+ *
+ * @param ctx - Plugin context carrying the read entry's project service.
+ * @param config - Deployment limits.
+ */
+export declare function apply(ctx: PluginContext, config?: Config): void;
+export { StudioState } from './studio-state.ts';
+export { studioTools } from './tools/studio.ts';
+export { controllerTools } from './tools/controller.ts';

package/vendor/l5x/lib/studio.js

@@ -0,0 +1,40 @@
+/**
+ * The L5X studio entry: offline SDK work over the read entry's project handles.
+ *
+ * Separate so the SDK's ACD export, build and verification schemas are paid for
+ * only where Studio 5000 is installed and the user opted in. No tool in this
+ * entry contacts a controller.
+ *
+ * @module dsh-engineering-l5x/studio
+ */
+import { StudioState } from "./studio-state.js";
+import { studioTools } from "./tools/studio.js";
+import { controllerTools } from "./tools/controller.js";
+import { PROJECTS_SERVICE } from "./index.js";
+/** Plugin name in a composition. */
+export const name = 'l5x-studio';
+/** The read entry's project service must already be mounted. */
+export const inject = ['tools', PROJECTS_SERVICE];
+/**
+ * Register the studio tools.
+ *
+ * @param ctx - Plugin context carrying the read entry's project service.
+ * @param config - Deployment limits.
+ */
+export function apply(ctx, config = {}) {
+    const session = ctx.get?.(PROJECTS_SERVICE);
+    if (session === undefined) {
+        throw new Error('l5x-studio: the l5xProjects service is unavailable; mount the L5X read entry before this one');
+    }
+    const maxFileBytes = config.maxFileBytes ?? 64 * 1024 * 1024;
+    if (!Number.isInteger(maxFileBytes) || maxFileBytes <= 0) {
+        throw new Error('l5x-studio: maxFileBytes must be a positive integer');
+    }
+    const state = new StudioState();
+    for (const definition of [...studioTools(session, state), ...controllerTools(session, state, ctx)]) {
+        ctx.tools.register(definition);
+    }
+}
+export { StudioState } from "./studio-state.js";
+export { studioTools } from "./tools/studio.js";
+export { controllerTools } from "./tools/controller.js";

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

@@ -0,0 +1,19 @@
+/**
+ * Checks and comparison: what is wrong with this export, and what changed
+ * between two exports.
+ *
+ * Both tools report evidence and limits rather than verdicts. A check finding is
+ * a candidate for engineering review, and a comparison covers parsed engineering
+ * content only — never timestamps or XML formatting.
+ *
+ * @module dsh-engineering-l5x/tools/checks
+ */
+import type { ToolDefinition } from '../core/tool.ts';
+import type { ProjectSession } from '../session.ts';
+/**
+ * The checks and comparison tools, bound to one chat's project store.
+ *
+ * @param session - Project handles for the calling chat.
+ * @returns Tool definitions in registration order.
+ */
+export declare function checkTools(session: ProjectSession): readonly ToolDefinition[];

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

@@ -0,0 +1,140 @@
+/**
+ * Checks and comparison: what is wrong with this export, and what changed
+ * between two exports.
+ *
+ * Both tools report evidence and limits rather than verdicts. A check finding is
+ * a candidate for engineering review, and a comparison covers parsed engineering
+ * content only — never timestamps or XML formatting.
+ *
+ * @module dsh-engineering-l5x/tools/checks
+ */
+import { runChecks, compareProjects } from "../engine/review.js";
+import { success } from "../core/result.js";
+import { choice, integer, object, string } from "../core/params.js";
+import { COVERAGE, PROJECT_ID, integerArg, optionalString, requiredString, tool } from "./common.js";
+/** Findings are candidates for review, not proof of safety. */
+const CHECK_COVERAGE = {
+    complete: false,
+    unverified: [
+        'findings are heuristics and require engineering review',
+        'external HMI, produced/consumed and driver consumers are not visible',
+        'absence of findings does not prove controller safety',
+    ],
+};
+/**
+ * The checks and comparison tools, bound to one chat's project store.
+ *
+ * @param session - Project handles for the calling chat.
+ * @returns Tool definitions in registration order.
+ */
+export function checkTools(session) {
+    return [
+        tool({
+            name: 'run_checks',
+            description: 'Run evidence-backed engineering checks on the open project: unused tags, unresolved references, unscheduled programs and undocumented logic. Pass baseline_id to add I/O change checks against an earlier export.',
+            parameters: object({
+                baseline_id: string('Optional second open project id to compare against, enabling I/O module change checks.'),
+                rule: string('Only return findings with this exact rule name. Example: "UNUSED_TAG".'),
+                severity: choice('Only return findings with this severity.', ['info', 'warning', 'critical']),
+                offset: integer('Zero-based index of the first finding to return.', { minimum: 0, default: 0 }),
+                limit: integer('Maximum findings to return.', { minimum: 1, maximum: 100, default: 20 }),
+                project_id: PROJECT_ID,
+            }, []),
+            async run(args, exec) {
+                const project = await session.require(optionalString(args, 'project_id'), exec);
+                const baselineId = optionalString(args, 'baseline_id');
+                const baseline = baselineId === undefined ? undefined : await session.require(baselineId, exec);
+                const result = runChecks(project, baseline);
+                const rule = optionalString(args, 'rule');
+                const severity = optionalString(args, 'severity');
+                const filtered = result.findings.filter(finding => (rule === undefined || finding.rule === rule) && (severity === undefined || finding.severity === severity));
+                const offset = integerArg(args, 'offset', 0);
+                const limit = Math.min(Math.max(integerArg(args, 'limit', 20), 1), 100);
+                const page = filtered.slice(offset, offset + limit);
+                const bySeverity = countBy(filtered, finding => finding.severity);
+                const byRule = countBy(filtered, finding => finding.rule);
+                const symbol = firstSymbol(page);
+                return success(`${filtered.length} ${filtered.length === 1 ? 'finding' : 'findings'}${rule === undefined ? '' : ` for rule ${rule}`} in ${project.document.controller.name}.`, {
+                    total: result.count,
+                    filtered_total: filtered.length,
+                    offset,
+                    limit,
+                    truncated: offset + limit < filtered.length,
+                    by_severity: bySeverity,
+                    by_rule: byRule,
+                    findings: page,
+                    note: result.note,
+                }, [
+                    ...(symbol === undefined
+                        ? []
+                        : [{ tool: 'find_references', args: { symbol }, why: 'Inspect the evidence behind the first finding.' }]),
+                    { tool: 'list_components', args: { kind: 'tag' }, why: 'Review declared tags before changing anything.' },
+                ], CHECK_COVERAGE);
+            },
+        }),
+        tool({
+            name: 'compare_projects',
+            description: 'Compare two open exports by engineering component: programs, tasks, tags, UDTs, AOIs, modules, alarms, routines, rungs, ST bodies and diagrams. Export timestamps and XML formatting are ignored.',
+            parameters: object({
+                before_id: string('Project id of the earlier export. Open both exports first with open_project.'),
+                after_id: string('Project id of the later export.'),
+                offset: integer('Zero-based index of the first change to return.', { minimum: 0, default: 0 }),
+                limit: integer('Maximum changes to return.', { minimum: 1, maximum: 100, default: 20 }),
+            }, ['before_id', 'after_id']),
+            async run(args, exec) {
+                const before = await session.require(requiredString(args, 'before_id'), exec);
+                const after = await session.require(requiredString(args, 'after_id'), exec);
+                const result = compareProjects(before, after);
+                const offset = integerArg(args, 'offset', 0);
+                const limit = Math.min(Math.max(integerArg(args, 'limit', 20), 1), 100);
+                const page = result.changes.slice(offset, offset + limit);
+                const byComponent = countBy(result.changes, change => change.component);
+                const byKind = countBy(result.changes, change => change.kind);
+                return success(`${result.count} ${result.count === 1 ? 'change' : 'changes'} between ${before.requestedPath} and ${after.requestedPath}.`, {
+                    before: result.before,
+                    after: result.after,
+                    count: result.count,
+                    offset,
+                    limit,
+                    truncated: offset + limit < result.count,
+                    by_component: byComponent,
+                    by_kind: byKind,
+                    changes: page,
+                }, [
+                    { tool: 'run_checks', args: { baseline_id: before.id }, why: 'Check I/O module changes against the earlier export.' },
+                    { tool: 'get_component', args: { kind: 'program', name: before.document.programs[0]?.name ?? '' }, why: 'Open a changed program in the later export.' },
+                ], {
+                    complete: false,
+                    unverified: [
+                        'binary or encoded content equivalence',
+                        'timestamps and XML formatting are ignored by design',
+                        ...COVERAGE.unverified,
+                    ],
+                });
+            },
+        }),
+    ];
+}
+/** Count values by a key function. */
+function countBy(values, key) {
+    const counts = {};
+    for (const value of values) {
+        const name = key(value);
+        counts[name] = (counts[name] ?? 0) + 1;
+    }
+    return counts;
+}
+/** The first symbol named in a finding's evidence, when there is one. */
+function firstSymbol(findings) {
+    for (const finding of findings) {
+        const evidence = finding.evidence;
+        if (evidence === null || typeof evidence !== 'object')
+            continue;
+        const record = evidence;
+        if (typeof record.tag === 'string' && record.tag !== '')
+            return record.tag;
+        if (typeof record.symbol === 'string' && record.symbol !== '')
+            return record.symbol;
+    }
+    return undefined;
+}

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

@@ -0,0 +1,41 @@
+/**
+ * Shared tool scaffolding: the envelope, the failure translation, and the
+ * argument readers every tool uses.
+ *
+ * @module dsh-engineering-l5x/tools/common
+ */
+import { type Parameters } from '../core/params.ts';
+import { type ExecContext, type ToolDefinition } from '../core/tool.ts';
+/** What this surface cannot establish, stated once. */
+export declare const COVERAGE: {
+    readonly complete: false;
+    readonly unverified: readonly ["FBD and SFC execution semantics", "dynamic indices", "runtime behavior", "external HMI, produced/consumed and driver consumers are not visible", "whether online logic matches the export"];
+};
+/** The handle every read can omit when one project is open. */
+export declare const PROJECT_ID: import("../core/params.ts").ParameterSchema;
+/** One tool body, before the shared envelope and error handling are attached. */
+export interface ToolSpec {
+    readonly name: string;
+    readonly description: string;
+    readonly parameters: Parameters;
+    run(args: Readonly<Record<string, unknown>>, exec: ExecContext): Promise<unknown>;
+}
+/**
+ * Attach the canonical output declaration and the failure envelope.
+ *
+ * @param spec - Tool name, description, parameters and body.
+ * @returns A registerable tool definition.
+ */
+export declare function tool(spec: ToolSpec): ToolDefinition;
+/** Whole-number argument with a default. */
+export declare function integerArg(args: Readonly<Record<string, unknown>>, name: string, fallback: number): number;
+/** A required string argument. */
+export declare function requiredString(args: Readonly<Record<string, unknown>>, name: string): string;
+/** A string argument, or undefined when absent or empty. */
+export declare function optionalString(args: Readonly<Record<string, unknown>>, name: string): string | undefined;
+/** An integer argument, or undefined when absent or not an integer. */
+export declare function optionalInteger(args: Readonly<Record<string, unknown>>, name: string): number | undefined;
+/** A number argument, or undefined when absent or not a finite number. */
+export declare function optionalNumber(args: Readonly<Record<string, unknown>>, name: string): number | undefined;
+/** The parameters object for a tool that takes no arguments but the project handle. */
+export declare function projectOnly(): Parameters;

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

@@ -0,0 +1,84 @@
+/**
+ * Shared tool scaffolding: the envelope, the failure translation, and the
+ * argument readers every tool uses.
+ *
+ * @module dsh-engineering-l5x/tools/common
+ */
+import { L5xError, errorEnvelope } from "../core/errors.js";
+import { object, string } from "../core/params.js";
+import { jsonText } from "../core/tool.js";
+/** What this surface cannot establish, stated once. */
+export const COVERAGE = {
+    complete: false,
+    unverified: [
+        'FBD and SFC execution semantics',
+        'dynamic indices',
+        'runtime behavior',
+        'external HMI, produced/consumed and driver consumers are not visible',
+        'whether online logic matches the export',
+    ],
+};
+/** The handle every read can omit when one project is open. */
+export const PROJECT_ID = string('Handle returned by open_project. Omit when exactly one project is open in this chat.', {});
+/**
+ * Attach the canonical output declaration and the failure envelope.
+ *
+ * @param spec - Tool name, description, parameters and body.
+ * @returns A registerable tool definition.
+ */
+export function tool(spec) {
+    return {
+        name: spec.name,
+        description: spec.description,
+        parameters: spec.parameters,
+        output: { schema: { type: 'object', additionalProperties: true }, render: jsonText },
+        async execute(args, exec) {
+            const context = {
+                ...(exec.signal === undefined ? {} : { signal: exec.signal }),
+                ...(exec.agent?.session?.header?.cwd === undefined ? {} : { cwd: exec.agent.session.header.cwd }),
+                ...(exec.agent?.session === undefined ? {} : { chat: exec.agent.session }),
+                ...(exec.callId === undefined ? {} : { callId: exec.callId }),
+                ...(exec.sessionId === undefined ? {} : { sessionId: exec.sessionId }),
+                ...(exec.agent === undefined ? {} : { agent: exec.agent }),
+            };
+            try {
+                return await spec.run(args, context);
+            }
+            catch (error) {
+                return errorEnvelope(error);
+            }
+        },
+    };
+}
+/** Whole-number argument with a default. */
+export function integerArg(args, name, fallback) {
+    const value = args[name];
+    return typeof value === 'number' && Number.isInteger(value) ? value : fallback;
+}
+/** A required string argument. */
+export function requiredString(args, name) {
+    const value = optionalString(args, name);
+    if (value === undefined) {
+        throw new L5xError('INVALID_ARGUMENT', `${name} is required.`, `Pass ${name} as a non-empty string.`);
+    }
+    return value;
+}
+/** A string argument, or undefined when absent or empty. */
+export function optionalString(args, name) {
+    const value = args[name];
+    return typeof value === 'string' && value !== '' ? value : undefined;
+}
+/** An integer argument, or undefined when absent or not an integer. */
+export function optionalInteger(args, name) {
+    const value = args[name];
+    return typeof value === 'number' && Number.isInteger(value) ? value : undefined;
+}
+/** A number argument, or undefined when absent or not a finite number. */
+export function optionalNumber(args, name) {
+    const value = args[name];
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+/** The parameters object for a tool that takes no arguments but the project handle. */
+export function projectOnly() {
+    return object({ project_id: PROJECT_ID }, []);
+}

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

@@ -0,0 +1,21 @@
+/**
+ * The supervised controller lifecycle: upload, connect, mode change, download.
+ *
+ * Only three actions change a machine — capture, mode change and download —
+ * and each one asks for per-call human approval of the exact controller, route
+ * and target before it sends anything. Reading is unapproved and read-only.
+ *
+ * @module dsh-engineering-l5x/tools/controller
+ */
+import type { PluginContext, ToolDefinition } from '../core/tool.ts';
+import type { ProjectSession } from '../session.ts';
+import type { StudioState } from '../studio-state.ts';
+/**
+ * The controller tools.
+ *
+ * @param session - Project handles for the calling chat.
+ * @param state - Verified builds and exports for the calling chat.
+ * @param ctx - Plugin context that may provide the approval service.
+ * @returns Tool definitions in registration order.
+ */
+export declare function controllerTools(session: ProjectSession, state: StudioState, ctx: PluginContext): readonly ToolDefinition[];

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

@@ -0,0 +1,170 @@
+/**
+ * The supervised controller lifecycle: upload, connect, mode change, download.
+ *
+ * Only three actions change a machine — capture, mode change and download —
+ * and each one asks for per-call human approval of the exact controller, route
+ * and target before it sends anything. Reading is unapproved and read-only.
+ *
+ * @module dsh-engineering-l5x/tools/controller
+ */
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { L5xError } from "../core/errors.js";
+import { success } from "../core/result.js";
+import { choice, object, string } from "../core/params.js";
+import { approvalStatus, ensureApprovalReady, requireHumanApproval } from "../approvals.js";
+import { captureControllerSnapshot, changeControllerMode, controllerActionPreflight, controllerUploadPreflight, downloadProject, goOnline, readControllerMode, readControllerModeForAction, readLiveTag, rememberControllerRoute, resolveControllerRoute, } from "../engine/studio-sdk.js";
+import { PROJECT_ID, optionalString, requiredString, tool } from "./common.js";
+/** A controller answer is not proof of the exported or edited logic. */
+const CONTROLLER_COVERAGE = {
+    complete: false,
+    unverified: [
+        'whether the controller is running the exported logic',
+        'physical machine behavior',
+        'values change between reads',
+    ],
+};
+/**
+ * The controller tools.
+ *
+ * @param session - Project handles for the calling chat.
+ * @param state - Verified builds and exports for the calling chat.
+ * @param ctx - Plugin context that may provide the approval service.
+ * @returns Tool definitions in registration order.
+ */
+export function controllerTools(session, state, ctx) {
+    return [
+        tool({
+            name: 'controller_approval_status',
+            description: 'Read this session\'s permission preset and human-approval policy before upload, mode change or download. Full access normally cannot ask for approval. No SDK, file search or controller access.',
+            parameters: object({}),
+            async run(_args, exec) {
+                const status = approvalStatus(ctx, exec);
+                return success(status.approved_controller_actions_requestable
+                    ? 'This session can request per-call approval for controller actions.'
+                    : 'This session cannot request approval for controller actions.', status, [], CONTROLLER_COVERAGE);
+            },
+        }),
+        tool({
+            name: 'capture_controller_snapshot',
+            description: 'Upload from the supplied controller IP to a new local ACD. Resolve the exact FactoryTalk Linx route from a named ACD or L5X; requires per-call human approval.',
+            parameters: object({
+                ip_address: string('Controller IPv4 address the human named. Example: "192.168.1.10".'),
+                route_project_path: string('ACD or L5X whose saved communications path names the controller route. Example: "C:/Projects/Line/Line.ACD".'),
+                output_path: string('New .ACD path for the upload. It must not exist.'),
+            }, ['ip_address', 'route_project_path', 'output_path']),
+            async run(args, exec) {
+                ensureApprovalReady(ctx, exec);
+                const ip = requiredString(args, 'ip_address');
+                const routePath = await session.resolvePath(requiredString(args, 'route_project_path'), exec);
+                const outputPath = await session.resolvePath(requiredString(args, 'output_path'), exec);
+                const commPath = await resolveControllerRoute(ip, routePath, exec.signal);
+                const output = await controllerUploadPreflight(commPath, outputPath);
+                await requireHumanApproval(ctx, exec, 'capture_controller_snapshot', `Upload controller at user-supplied IP ${ip} using verified FactoryTalk Linx route ${commPath} into new local ACD ${output}`);
+                const result = await captureControllerSnapshot(commPath, output, exec.signal);
+                await rememberControllerRoute(ip, result.output_path, commPath);
+                return success(`Uploaded controller at ${ip} to ${result.output_path}.`, { ip_address: ip, ...result }, [], CONTROLLER_COVERAGE);
+            },
+        }),
+        tool({
+            name: 'go_online',
+            description: 'Connect a matching ACD to a controller for read-only diagnostics. Does not change mode or controller data.',
+            parameters: object({
+                snapshot_path: string('ACD uploaded from that controller. Example: "C:/Projects/Line/Upload.ACD".'),
+                ip_address: string('Controller IPv4 address. Example: "192.168.1.10".'),
+            }, ['snapshot_path', 'ip_address']),
+            async run(args, exec) {
+                const ip = requiredString(args, 'ip_address');
+                const snapshot = await session.resolvePath(requiredString(args, 'snapshot_path'), exec);
+                return success(`Connected ${snapshot} to ${ip}.`, { ip_address: ip, ...await goOnline(snapshot, await resolveControllerRoute(ip, snapshot, exec.signal), exec.signal) }, [], CONTROLLER_COVERAGE);
+            },
+        }),
+        tool({
+            name: 'read_controller_mode',
+            description: 'Read controller mode for the explicitly supplied controller IP. Supply the matching snapshot ACD to avoid reimporting an L5X. Read-only.',
+            parameters: object({
+                project_id: PROJECT_ID,
+                ip_address: string('Controller IPv4 address. Example: "192.168.1.10".'),
+                snapshot_path: string('Optional matching ACD upload. Omit to use the open project\u2019s path for the route.'),
+            }, ['ip_address']),
+            async run(args, exec) {
+                const project = await session.require(optionalString(args, 'project_id'), exec);
+                const ip = requiredString(args, 'ip_address');
+                const snapshotArg = optionalString(args, 'snapshot_path');
+                const snapshot = snapshotArg === undefined ? undefined : await session.resolvePath(snapshotArg, exec);
+                return success(`Read mode from ${ip}.`, { ip_address: ip, ...await readControllerMode(project, await resolveControllerRoute(ip, snapshot ?? project.path, exec.signal), exec.signal, snapshot) }, [], CONTROLLER_COVERAGE);
+            },
+        }),
+        tool({
+            name: 'read_live_tag',
+            description: 'Read one controller-scoped scalar BOOL, INT, DINT or REAL from a matching uploaded ACD. Supply the declared data type; read-only.',
+            parameters: object({
+                snapshot_path: string('ACD uploaded from that controller.'),
+                ip_address: string('Controller IPv4 address.'),
+                tag: string('Controller-scoped tag name. Example: "LineSpeed".'),
+                data_type: choice('Declared scalar type.', ['BOOL', 'INT', 'DINT', 'REAL']),
+            }, ['snapshot_path', 'ip_address', 'tag', 'data_type']),
+            async run(args, exec) {
+                const ip = requiredString(args, 'ip_address');
+                const snapshot = await session.resolvePath(requiredString(args, 'snapshot_path'), exec);
+                const dataType = requiredString(args, 'data_type');
+                return success(`Read ${requiredString(args, 'tag')} from ${ip}.`, { ip_address: ip, ...await readLiveTag(snapshot, await resolveControllerRoute(ip, snapshot, exec.signal), requiredString(args, 'tag'), dataType, exec.signal) }, [], CONTROLLER_COVERAGE);
+            },
+        }),
+        tool({
+            name: 'change_controller_mode',
+            description: 'Change controller mode to Program, Run or Test. Requires per-call human approval for the exact controller and target mode.',
+            parameters: object({
+                snapshot_path: string('Matching ACD for the controller.'),
+                ip_address: string('Controller IPv4 address.'),
+                target_mode: choice('Mode the human approved.', ['Program', 'Run', 'Test']),
+            }, ['snapshot_path', 'ip_address', 'target_mode']),
+            async run(args, exec) {
+                ensureApprovalReady(ctx, exec);
+                const ip = requiredString(args, 'ip_address');
+                const snapshot = await session.resolvePath(requiredString(args, 'snapshot_path'), exec);
+                const mode = requiredString(args, 'target_mode');
+                if (!['Program', 'Run', 'Test'].includes(mode)) {
+                    throw new L5xError('INVALID_MODE', 'target_mode must be Program, Run or Test.', 'Pass one of: Program, Run, Test.');
+                }
+                const commPath = await resolveControllerRoute(ip, snapshot, exec.signal);
+                const preflight = await controllerActionPreflight(snapshot, commPath);
+                const currentMode = await readControllerModeForAction(preflight, commPath, exec.signal);
+                if (currentMode === mode) {
+                    throw new L5xError('MODE_ALREADY_SET', `The controller is already in ${mode} mode.`, 'Read the mode and report it; no change is needed.');
+                }
+                await requireHumanApproval(ctx, exec, 'change_controller_mode', `Change controller at user-supplied IP ${ip} via ${commPath} from ${currentMode} to ${mode} mode using ${preflight.path} (SHA-256 ${preflight.sha256})`);
+                return success(`Changed controller at ${ip} from ${currentMode} to ${mode} mode.`, { ip_address: ip, ...await changeControllerMode(preflight, commPath, mode, currentMode, exec.signal) }, [], CONTROLLER_COVERAGE);
+            },
+        }),
+        tool({
+            name: 'download_project',
+            description: 'Download only an ACD built and reviewed by verify_offline_l5x or build_acd_from_draft in this chat, using its verification_id. Requires per-call human approval; never changes mode automatically.',
+            parameters: object({
+                verification_id: string('Verification id returned by a passed offline build. Example: "b1f2...".'),
+                ip_address: string('Controller IPv4 address the human named.'),
+            }, ['verification_id', 'ip_address']),
+            async run(args, exec) {
+                ensureApprovalReady(ctx, exec);
+                const id = requiredString(args, 'verification_id');
+                const ip = requiredString(args, 'ip_address');
+                const verified = state.verified(exec, id);
+                if (verified === undefined) {
+                    throw new L5xError('UNVERIFIED_ACD', 'No successful SDK build and baseline review exists for this verification_id in this chat.', 'Run verify_offline_l5x or build_acd_from_draft until it returns download_ready true, then use that verification_id.');
+                }
+                const commPath = await resolveControllerRoute(ip, verified.baselinePath, exec.signal);
+                const baselineHash = createHash('sha256').update(await readFile(verified.baselinePath)).digest('hex');
+                const sourceHash = createHash('sha256').update(await readFile(verified.sourcePath)).digest('hex');
+                if (baselineHash !== verified.review.baseline_sha256 || sourceHash !== verified.review.source_sha256) {
+                    throw new L5xError('STALE_EXPORT', 'The baseline or edited L5X changed after SDK verification.', 'Build again, then download that new verification id.');
+                }
+                const preflight = await controllerActionPreflight(verified.path, commPath);
+                if (preflight.sha256 !== verified.sha256) {
+                    throw new L5xError('ACD_CHANGED', 'The built ACD changed after SDK verification.', 'Build again, then download that new verification id.');
+                }
+                await requireHumanApproval(ctx, exec, 'download_project', `Download ACD ${verified.path} (SHA-256 ${verified.sha256}) to controller at user-supplied IP ${ip} via ${commPath}; mode is not changed`);
+                return success(`Downloaded the verified build to ${ip}.`, { ip_address: ip, verification_id: id, ...await downloadProject(preflight, commPath, exec.signal) }, [], CONTROLLER_COVERAGE);
+            },
+        }),
+    ];
+}

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

@@ -0,0 +1,23 @@
+/**
+ * The draft family: one operation per call, accumulated, validated, applied.
+ *
+ * Replaces a single tool that took a JSON string of every operation. Each tool
+ * here is flat, names its own intent, and returns the growing operation count,
+ * so a small model can see the draft take shape without holding a nested
+ * document in its head.
+ *
+ * @module dsh-engineering-l5x/tools/drafts
+ */
+import type { ToolDefinition } from '../core/tool.ts';
+import type { ProjectSession } from '../session.ts';
+import type { DraftStore } from '../drafts.ts';
+/**
+ * The draft tools, bound to one chat's project and draft stores.
+ *
+ * @param session - Project handles for the calling chat.
+ * @param drafts - Drafts for the calling chat.
+ * @param maxOperations - Inclusive operations per draft.
+ * @param maxFileBytes - Byte budget the preparation may read.
+ * @returns Tool definitions in registration order.
+ */
+export declare function draftTools(session: ProjectSession, drafts: DraftStore, maxOperations: number, maxFileBytes: number): readonly ToolDefinition[];