@tenonhq/dovetail-servicenow 0.0.14 → 0.0.16

package/README.md

@@ -195,6 +195,12 @@ npx dove-sn test-flow --sys-id <sys_id> --execute --confirm --inputs '{...}'  #
 echo '{"rename":{"name":"New Name"},"patchStepInputs":[{"step":"Calculate SMS Send At","input":"send_rate","value":"5"}]}' > ops.json
 npx dove-sn edit-flow --sys-id <sys_id> --from-json ops.json                          # dry-run (diff)
 npx dove-sn edit-flow --sys-id <sys_id> --from-json ops.json --apply --update-set <id> # persist
+
+# Edit a Custom Action Type's script and/or output variables, then republish (headless)
+npx dove-sn edit-action --sys-id <action_type_sys_id> --scope <scope_sys_id> \
+  --patch-script "grabHashData::grabRecipients"                                   # dry-run (diff)
+npx dove-sn edit-action --sys-id <id> --scope <scope> --set-script ./script.js \
+  --merge-outputs ./output-var.json --apply --update-set <id>                     # persist + publish
 ```
 
 `copy-flow` calls the Designer's own `POST /processflow/flow/{id}/copy` — a
@@ -228,6 +234,17 @@ Step-input persistence via the snapshot POST is verified for action types but is
 and **warns** if a value didn't actually persist, so a no-op never reports as a
 silent success.
 
+`edit-action` edits a **published Custom Action Type** headlessly: it GETs the
+model, fetches the steps from `.../{id}/step_instances` (the model GET returns
+`steps:null`), patches the script step input (`--patch-script "<find>::<replace>"`
+or `--set-script <file>`) and/or merges output-variable definitions
+(`--merge-outputs <json>`, matched by `name`), grafts the steps back, and POSTs
+`/snapshot` to recompile — the same snapshot POST `publishActionType` uses, which
+persists step input values back to `sys_variable_value`. It deliberately avoids
+the Designer's model PUT, whose client-side step transform is unsafe to
+hand-reconstruct. Dry-run (diff) by default; `--apply` republishes, and
+`--update-set <id>` pins the capture into a chosen update set.
+
 `view-flow` reads `GET /api/now/processflow/flow/{id}` — the Designer's own model
 endpoint — and prints the ordered, nesting-aware action + flow-logic step graph
 plus the flow variables. This works for the integration user with plain basic

package/dist/cli.js

@@ -75,6 +75,7 @@ const publishFlow_1 = require("./flowDesigner/publishFlow");
 const copyFlow_1 = require("./flowDesigner/copyFlow");
 const createFlow_1 = require("./flowDesigner/createFlow");
 const editFlow_1 = require("./flowDesigner/editFlow");
+const editActionType_1 = require("./flowDesigner/editActionType");
 const testFlow_1 = require("./flowDesigner/testFlow");
 const flowDesigner_formatter_2 = require("./flowDesigner-formatter");
 function parseArgs(argv) {
@@ -595,6 +596,72 @@ async function runEditFlow(flags) {
     }
     return 0;
 }
+/**
+ * dove-sn edit-action:
+ *   --sys-id <sys_id>                  Required. sys_hub_action_type_definition sys_id.
+ *   --scope <sys_id>                   Required. sysparm_transaction_scope (app scope sys_id).
+ *   --patch-script "<find>::<replace>" Optional. Find/replace in the script step value.
+ *   --set-script <path>                Optional. Replace the script step value from a file.
+ *   --merge-outputs <path>             Optional. JSON file: an output-variable object/array to merge by name.
+ *   --script-input <name>              Optional. Input name holding the script (default: auto-detect).
+ *   --update-set <sys_id>              Optional. Capture the republish into this update set.
+ *   --apply                            Optional. Republish (POST /snapshot). Omit for dry-run.
+ *   --json                             Optional. Emit the structured EditActionTypeResult.
+ *
+ * Edits a published Custom Action Type's script and/or output variables and
+ * republishes through the snapshot POST. Dry-run (read-only) by default; --apply writes.
+ */
+async function runEditAction(flags) {
+    var sysId = flags["sys-id"] || flags.sysId;
+    var scope = flags.scope || flags.scopeSysId;
+    if (!sysId || !scope) {
+        process.stderr.write("edit-action: --sys-id <sys_id> and --scope <sys_id> are required\n");
+        return 1;
+    }
+    var ops = {};
+    if (flags["patch-script"]) {
+        var parts = String(flags["patch-script"]).split("::");
+        if (parts.length !== 2) {
+            process.stderr.write("edit-action: --patch-script must be \"<find>::<replace>\"\n");
+            return 1;
+        }
+        ops.patchScript = { find: parts[0], replace: parts[1] };
+    }
+    if (flags["set-script"]) {
+        ops.setScript = fs.readFileSync(flags["set-script"], "utf8");
+    }
+    if (flags["merge-outputs"]) {
+        var parsedOutputs = JSON.parse(fs.readFileSync(flags["merge-outputs"], "utf8"));
+        ops.mergeOutputs = Array.isArray(parsedOutputs) ? parsedOutputs : [parsedOutputs];
+    }
+    if (flags["script-input"]) {
+        ops.scriptInputName = flags["script-input"];
+    }
+    var result = await (0, editActionType_1.editActionType)({
+        client: (0, client_1.createClient)({}),
+        sysId: sysId,
+        scopeSysId: scope,
+        ops: ops,
+        apply: flags.apply === "true",
+        updateSetSysId: flags["update-set"] || flags.updateSetSysId
+    });
+    if (flags.json === "true") {
+        process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+        return 0;
+    }
+    process.stdout.write("[" + result.status + "] " + result.changes.length + " change(s)"
+        + (result.snapshotSysId ? " — snapshot " + result.snapshotSysId : "") + "\n");
+    for (var ci = 0; ci < result.changes.length; ci += 1) {
+        process.stdout.write("  + " + result.changes[ci] + "\n");
+    }
+    for (var wi = 0; wi < result.warnings.length; wi += 1) {
+        process.stdout.write("  ! " + result.warnings[wi] + "\n");
+    }
+    if (result.status === "preview" && result.scriptAfter !== undefined && result.scriptAfter !== result.scriptBefore) {
+        process.stdout.write("\n--- script after ---\n" + result.scriptAfter + "\n");
+    }
+    return 0;
+}
 async function runMcp(flags) {
     if (flags.smoke === "true") {
         await (0, server_1.runSmoke)();
@@ -675,6 +742,9 @@ async function main() {
     if (parsed.command === "edit-flow") {
         return await runEditFlow(parsed.flags);
     }
+    if (parsed.command === "edit-action") {
+        return await runEditAction(parsed.flags);
+    }
     if (parsed.command === "create-view") {
         await runCreateView(parsed.flags);
         return 0;

package/dist/flowDesigner/editActionType.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Edit a published Custom Action Type's script and/or output variables, then
+ * republish — entirely headless, basic auth, no Designer UI.
+ *
+ * Reuses the validated publish contract (see publishActionType):
+ *   GET  /api/now/processflow/action/action_types/{id}                -> model (outputs[], steps:null)
+ *   GET  /api/now/processflow/action/action_types/{id}/step_instances -> { steps:[...] } (carries the script)
+ *   POST /api/now/processflow/action/action_types/{id}/snapshot       -> 201; compiles the snapshot AND
+ *                                                                        persists step input values back to
+ *                                                                        sys_variable_value
+ *
+ * The GET model returns `steps: null` (the Designer assembles them client-side),
+ * so we fetch them from `/step_instances`, patch the script input there,
+ * optionally merge output-variable definitions into `model.outputs`, graft the
+ * steps back onto the model, and POST `/snapshot`. Because the snapshot POST
+ * persists step input values, the patched script lands without a separate write.
+ *
+ * Why route through `/snapshot` rather than the Designer's model PUT: the PUT
+ * applies a client-side model transform (it strips ~14 step fields and reshapes
+ * inputs) that is unsafe to hand-reconstruct and risks corrupting the action.
+ * The snapshot POST is the path publishActionType already proved end to end.
+ *
+ * Full write-up: docs/servicenow-flow-designer-headless-authoring.md.
+ */
+import type { ServiceNowClient } from "../client";
+export interface EditActionTypeOps {
+    /** Replace every occurrence of `find` with `replace` inside the script step value. */
+    patchScript?: {
+        find: string;
+        replace: string;
+    };
+    /** Replace the script step value outright (wins over patchScript). */
+    setScript?: string;
+    /**
+     * Output-variable definition objects to merge into `model.outputs`, matched by
+     * `name` (replaced in place, else appended). Supply the modeled output JSON —
+     * e.g. an `array.object` with `children` — typically lifted from a Designer
+     * capture of the same shape.
+     */
+    mergeOutputs?: Array<Record<string, any>>;
+    /**
+     * The input `name` holding the script. Defaults to auto-detect: the first step
+     * input whose value reads like an action script.
+     */
+    scriptInputName?: string;
+}
+export interface EditActionTypeParams {
+    client: ServiceNowClient;
+    /** sys_id of the sys_hub_action_type_definition to edit. */
+    sysId: string;
+    /** Application scope sys_id, passed as sysparm_transaction_scope. */
+    scopeSysId: string;
+    ops: EditActionTypeOps;
+    /** When true, republish. When false/omitted, dry-run (no write). */
+    apply?: boolean;
+    /** Update set to capture the publish into (pins the REST session's active set first). */
+    updateSetSysId?: string;
+}
+export interface EditActionTypeResult {
+    status: "preview" | "published";
+    changes: Array<string>;
+    warnings: Array<string>;
+    scriptBefore?: string;
+    scriptAfter?: string;
+    outputsMerged: Array<string>;
+    /** HTTP status of the snapshot POST (201 on success); only set when applied. */
+    httpStatus?: number;
+    snapshotSysId?: string;
+}
+export declare function editActionType(params: EditActionTypeParams): Promise<EditActionTypeResult>;

package/dist/flowDesigner/editActionType.js

@@ -0,0 +1,196 @@
+"use strict";
+/**
+ * Edit a published Custom Action Type's script and/or output variables, then
+ * republish — entirely headless, basic auth, no Designer UI.
+ *
+ * Reuses the validated publish contract (see publishActionType):
+ *   GET  /api/now/processflow/action/action_types/{id}                -> model (outputs[], steps:null)
+ *   GET  /api/now/processflow/action/action_types/{id}/step_instances -> { steps:[...] } (carries the script)
+ *   POST /api/now/processflow/action/action_types/{id}/snapshot       -> 201; compiles the snapshot AND
+ *                                                                        persists step input values back to
+ *                                                                        sys_variable_value
+ *
+ * The GET model returns `steps: null` (the Designer assembles them client-side),
+ * so we fetch them from `/step_instances`, patch the script input there,
+ * optionally merge output-variable definitions into `model.outputs`, graft the
+ * steps back onto the model, and POST `/snapshot`. Because the snapshot POST
+ * persists step input values, the patched script lands without a separate write.
+ *
+ * Why route through `/snapshot` rather than the Designer's model PUT: the PUT
+ * applies a client-side model transform (it strips ~14 step fields and reshapes
+ * inputs) that is unsafe to hand-reconstruct and risks corrupting the action.
+ * The snapshot POST is the path publishActionType already proved end to end.
+ *
+ * Full write-up: docs/servicenow-flow-designer-headless-authoring.md.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.editActionType = editActionType;
+function actionTypePath(sysId, scopeSysId, suffix) {
+    return "/api/now/processflow/action/action_types/" + encodeURIComponent(sysId)
+        + suffix
+        + "?sysparm_transaction_scope=" + encodeURIComponent(scopeSysId);
+}
+/** Normalize the `{ result: ... }` envelope the processflow endpoints sometimes use. */
+function unwrap(data) {
+    if (data && typeof data === "object" && data.result && typeof data.result === "object") {
+        return data.result;
+    }
+    return data;
+}
+var SCRIPT_SIGNATURE = /function execute|inputs\.|outputs\.|new\s+[A-Za-z_$]/;
+/** Locate the step input holding the action script (by name, else by signature). */
+function findScriptInput(steps, inputName) {
+    for (var s = 0; s < steps.length; s += 1) {
+        var inputs = (steps[s] && steps[s].inputs) || [];
+        for (var i = 0; i < inputs.length; i += 1) {
+            var inp = inputs[i];
+            if (!inp) {
+                continue;
+            }
+            if (inputName) {
+                if (inp.name === inputName) {
+                    return { input: inp };
+                }
+            }
+            else if (typeof inp.value === "string" && inp.value.length > 30 && SCRIPT_SIGNATURE.test(inp.value)) {
+                return { input: inp };
+            }
+        }
+    }
+    return null;
+}
+async function editActionType(params) {
+    var client = params.client;
+    var sysId = params.sysId;
+    var scopeSysId = params.scopeSysId;
+    var ops = params.ops || {};
+    if (!sysId) {
+        throw new Error("editActionType: sysId is required.");
+    }
+    if (!scopeSysId) {
+        throw new Error("editActionType: scopeSysId is required (sysparm_transaction_scope).");
+    }
+    if (!ops.patchScript && !ops.setScript && !(ops.mergeOutputs && ops.mergeOutputs.length > 0)) {
+        throw new Error("editActionType: no ops — supply patchScript, setScript, and/or mergeOutputs.");
+    }
+    var changes = [];
+    var warnings = [];
+    var outputsMerged = [];
+    // 1. GET the model (outputs[], steps:null).
+    var model = unwrap(await client.now.get(actionTypePath(sysId, scopeSysId, "")));
+    if (!model || typeof model !== "object") {
+        throw new Error("editActionType: unexpected GET model response for action type " + sysId);
+    }
+    // 2. GET the steps — the model's `steps` come back null.
+    var stepsResp = unwrap(await client.now.get(actionTypePath(sysId, scopeSysId, "/step_instances")));
+    var steps = stepsResp && Array.isArray(stepsResp.steps) ? stepsResp.steps : [];
+    if (steps.length === 0) {
+        throw new Error("editActionType: /step_instances returned no steps for action type " + sysId);
+    }
+    // 3. Patch the script step input.
+    var scriptBefore;
+    var scriptAfter;
+    if (ops.patchScript || ops.setScript) {
+        var hit = findScriptInput(steps, ops.scriptInputName);
+        if (!hit) {
+            warnings.push("script input not found" + (ops.scriptInputName ? " (name=" + ops.scriptInputName + ")" : " (auto-detect)"));
+        }
+        else {
+            scriptBefore = String(hit.input.value);
+            if (ops.setScript) {
+                scriptAfter = ops.setScript;
+            }
+            else if (ops.patchScript) {
+                if (scriptBefore.indexOf(ops.patchScript.find) === -1) {
+                    warnings.push("patchScript.find not present in script: " + ops.patchScript.find);
+                    scriptAfter = scriptBefore;
+                }
+                else {
+                    scriptAfter = scriptBefore.split(ops.patchScript.find).join(ops.patchScript.replace);
+                }
+            }
+            if (scriptAfter !== undefined && scriptAfter !== scriptBefore) {
+                hit.input.value = scriptAfter;
+                changes.push("script input '" + hit.input.name + "' patched");
+            }
+            else {
+                warnings.push("script unchanged");
+            }
+        }
+    }
+    // 4. Merge output-variable definitions by name.
+    if (ops.mergeOutputs && ops.mergeOutputs.length > 0) {
+        if (!Array.isArray(model.outputs)) {
+            model.outputs = [];
+        }
+        for (var od = 0; od < ops.mergeOutputs.length; od += 1) {
+            var outDef = ops.mergeOutputs[od];
+            var outName = outDef && outDef.name;
+            if (!outName) {
+                warnings.push("mergeOutputs entry missing name — skipped");
+                continue;
+            }
+            var replaced = false;
+            for (var m = 0; m < model.outputs.length; m += 1) {
+                if (model.outputs[m] && model.outputs[m].name === outName) {
+                    model.outputs[m] = outDef;
+                    replaced = true;
+                    break;
+                }
+            }
+            if (!replaced) {
+                model.outputs.push(outDef);
+            }
+            outputsMerged.push(outName);
+            changes.push("output '" + outName + "' " + (replaced ? "replaced" : "added"));
+        }
+    }
+    // 5. Graft steps onto the model (remap each step's `action` to this sysId, per
+    //    the publish contract).
+    model.steps = steps.map(function (step) {
+        var copy = {};
+        for (var key in step) {
+            if (Object.prototype.hasOwnProperty.call(step, key)) {
+                copy[key] = step[key];
+            }
+        }
+        copy.action = sysId;
+        return copy;
+    });
+    if (!params.apply) {
+        return {
+            status: "preview",
+            changes: changes,
+            warnings: warnings,
+            scriptBefore: scriptBefore,
+            scriptAfter: scriptAfter,
+            outputsMerged: outputsMerged
+        };
+    }
+    // 6. Apply: optionally pin the update set, then POST /snapshot (compiles the
+    //    snapshot and persists step input values).
+    if (params.updateSetSysId) {
+        await client.claude.changeUpdateSet({ sysId: params.updateSetSysId });
+    }
+    var snapResp = unwrap(await client.now.post(actionTypePath(sysId, scopeSysId, "/snapshot"), model));
+    var snapshotSysId;
+    if (snapResp && typeof snapResp === "object") {
+        var snap = snapResp.latest_snapshot || snapResp.master_snapshot || snapResp.snapshot;
+        if (snap && typeof snap === "object") {
+            snapshotSysId = typeof snap.sys_id === "string" ? snap.sys_id : undefined;
+        }
+        else if (typeof snap === "string") {
+            snapshotSysId = snap;
+        }
+    }
+    return {
+        status: "published",
+        changes: changes,
+        warnings: warnings,
+        scriptBefore: scriptBefore,
+        scriptAfter: scriptAfter,
+        outputsMerged: outputsMerged,
+        httpStatus: 201,
+        snapshotSysId: snapshotSysId
+    };
+}

package/dist/flowDesigner/index.d.ts

@@ -16,6 +16,8 @@ export { triggerPublication } from "./triggerPublication";
 export type { TriggerPublicationParams, TriggerPublicationResult } from "./triggerPublication";
 export { publishActionType } from "./publishActionType";
 export type { PublishActionTypeParams, PublishActionTypeResult } from "./publishActionType";
+export { editActionType } from "./editActionType";
+export type { EditActionTypeParams, EditActionTypeResult, EditActionTypeOps } from "./editActionType";
 export { readFlow } from "./readFlow";
 export type { ReadFlowParams, ReadFlowResult, FlowStep, FlowVariable } from "./readFlow";
 export { readActionType } from "./readActionType";

package/dist/flowDesigner/index.js

@@ -6,7 +6,7 @@
  * functions land in Phase 1.C/D.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WriteOrderError = exports.executeWritePlan = exports.topoSort = exports.SYSTEM_FIELDS_TO_STRIP = exports.assertSysId = exports.applyScope = exports.stripSystemFields = exports.generateSysId = exports.DEFAULT_RUN_FLOW_PATH = exports.testFlow = exports.editFlow = exports.buildPublishModel = exports.createFlow = exports.copyFlow = exports.publishFlow = exports.readActionType = exports.readFlow = exports.publishActionType = exports.triggerPublication = exports.cloneActionType = exports.cloneSubflow = exports.verifyArtifact = exports.listTemplates = void 0;
+exports.WriteOrderError = exports.executeWritePlan = exports.topoSort = exports.SYSTEM_FIELDS_TO_STRIP = exports.assertSysId = exports.applyScope = exports.stripSystemFields = exports.generateSysId = exports.DEFAULT_RUN_FLOW_PATH = exports.testFlow = exports.editFlow = exports.buildPublishModel = exports.createFlow = exports.copyFlow = exports.publishFlow = exports.readActionType = exports.readFlow = exports.editActionType = exports.publishActionType = exports.triggerPublication = exports.cloneActionType = exports.cloneSubflow = exports.verifyArtifact = exports.listTemplates = void 0;
 var listTemplates_1 = require("./listTemplates");
 Object.defineProperty(exports, "listTemplates", { enumerable: true, get: function () { return listTemplates_1.listTemplates; } });
 var verifyArtifact_1 = require("./verifyArtifact");
@@ -19,6 +19,8 @@ var triggerPublication_1 = require("./triggerPublication");
 Object.defineProperty(exports, "triggerPublication", { enumerable: true, get: function () { return triggerPublication_1.triggerPublication; } });
 var publishActionType_1 = require("./publishActionType");
 Object.defineProperty(exports, "publishActionType", { enumerable: true, get: function () { return publishActionType_1.publishActionType; } });
+var editActionType_1 = require("./editActionType");
+Object.defineProperty(exports, "editActionType", { enumerable: true, get: function () { return editActionType_1.editActionType; } });
 var readFlow_1 = require("./readFlow");
 Object.defineProperty(exports, "readFlow", { enumerable: true, get: function () { return readFlow_1.readFlow; } });
 var readActionType_1 = require("./readActionType");

package/dist/index.d.ts

@@ -14,6 +14,6 @@ export { setFormLayout } from "./layout/formLayout";
 export { setRelatedLists } from "./layout/relatedLists";
 export { formatLayoutResult, formatCreateViewResult } from "./layout/formatter";
 export { sincPlugin } from "./plugin";
-export { listTemplates, verifyArtifact, cloneSubflow, cloneActionType, triggerPublication, publishActionType, readFlow, readActionType, publishFlow, copyFlow, createFlow, buildPublishModel, editFlow, testFlow, DEFAULT_RUN_FLOW_PATH, generateSysId, topoSort, executeWritePlan, WriteOrderError } from "./flowDesigner";
-export type { TemplateRef, ListTemplatesParams, FlowKind, VerifyExpect, VerifyFound, VerifyFailure, VerifyReport, VerifyArtifactParams, CloneSubflowParams, CloneSubflowResult, CloneActionTypeParams, CloneActionTypeResult, TriggerPublicationParams, TriggerPublicationResult, PublishActionTypeParams, PublishActionTypeResult, ReadFlowParams, ReadFlowResult, FlowStep, FlowVariable, ReadActionTypeParams, ReadActionTypeResult, ActionIo, PublishFlowParams, PublishFlowResult, CopyFlowParams, CopyFlowResult, CreateFlowParams, CreateFlowResult, EditFlowParams, EditFlowResult, EditFlowOps, StepInputPatch, TestFlowParams, TestFlowResult, WriteOp, WriteOpResult } from "./flowDesigner";
+export { listTemplates, verifyArtifact, cloneSubflow, cloneActionType, triggerPublication, publishActionType, editActionType, readFlow, readActionType, publishFlow, copyFlow, createFlow, buildPublishModel, editFlow, testFlow, DEFAULT_RUN_FLOW_PATH, generateSysId, topoSort, executeWritePlan, WriteOrderError } from "./flowDesigner";
+export type { TemplateRef, ListTemplatesParams, FlowKind, VerifyExpect, VerifyFound, VerifyFailure, VerifyReport, VerifyArtifactParams, CloneSubflowParams, CloneSubflowResult, CloneActionTypeParams, CloneActionTypeResult, TriggerPublicationParams, TriggerPublicationResult, PublishActionTypeParams, PublishActionTypeResult, EditActionTypeParams, EditActionTypeResult, EditActionTypeOps, ReadFlowParams, ReadFlowResult, FlowStep, FlowVariable, ReadActionTypeParams, ReadActionTypeResult, ActionIo, PublishFlowParams, PublishFlowResult, CopyFlowParams, CopyFlowResult, CreateFlowParams, CreateFlowResult, EditFlowParams, EditFlowResult, EditFlowOps, StepInputPatch, TestFlowParams, TestFlowResult, WriteOp, WriteOpResult } from "./flowDesigner";
 export type { ServiceNowClientConfig, ChoiceValue, ChoiceType, AddChoicesParams, AddChoicesResult, ChoiceActionResult, DictionaryRecord, UpdateSetRecord, LayoutAction, LayoutRecordResult, LayoutResult, CreateViewParams, CreateViewResult, FormSectionSpec, SetFormLayoutParams, SetListLayoutParams, SetRelatedListsParams } from "./types";

package/dist/index.js

@@ -6,7 +6,7 @@
  * REST API so every change lands in the target update set and scope.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WriteOrderError = exports.executeWritePlan = exports.topoSort = exports.generateSysId = exports.DEFAULT_RUN_FLOW_PATH = exports.testFlow = exports.editFlow = exports.buildPublishModel = exports.createFlow = exports.copyFlow = exports.publishFlow = exports.readActionType = exports.readFlow = exports.publishActionType = exports.triggerPublication = exports.cloneActionType = exports.cloneSubflow = exports.verifyArtifact = exports.listTemplates = exports.sincPlugin = exports.formatCreateViewResult = exports.formatLayoutResult = exports.setRelatedLists = exports.setFormLayout = exports.setListLayout = exports.createView = exports.formatAddChoicesResult = exports.addChoicesToField = exports.createClient = void 0;
+exports.WriteOrderError = exports.executeWritePlan = exports.topoSort = exports.generateSysId = exports.DEFAULT_RUN_FLOW_PATH = exports.testFlow = exports.editFlow = exports.buildPublishModel = exports.createFlow = exports.copyFlow = exports.publishFlow = exports.readActionType = exports.readFlow = exports.editActionType = exports.publishActionType = exports.triggerPublication = exports.cloneActionType = exports.cloneSubflow = exports.verifyArtifact = exports.listTemplates = exports.sincPlugin = exports.formatCreateViewResult = exports.formatLayoutResult = exports.setRelatedLists = exports.setFormLayout = exports.setListLayout = exports.createView = exports.formatAddChoicesResult = exports.addChoicesToField = exports.createClient = void 0;
 var client_1 = require("./client");
 Object.defineProperty(exports, "createClient", { enumerable: true, get: function () { return client_1.createClient; } });
 var choices_1 = require("./choices");
@@ -33,6 +33,7 @@ Object.defineProperty(exports, "cloneSubflow", { enumerable: true, get: function
 Object.defineProperty(exports, "cloneActionType", { enumerable: true, get: function () { return flowDesigner_1.cloneActionType; } });
 Object.defineProperty(exports, "triggerPublication", { enumerable: true, get: function () { return flowDesigner_1.triggerPublication; } });
 Object.defineProperty(exports, "publishActionType", { enumerable: true, get: function () { return flowDesigner_1.publishActionType; } });
+Object.defineProperty(exports, "editActionType", { enumerable: true, get: function () { return flowDesigner_1.editActionType; } });
 Object.defineProperty(exports, "readFlow", { enumerable: true, get: function () { return flowDesigner_1.readFlow; } });
 Object.defineProperty(exports, "readActionType", { enumerable: true, get: function () { return flowDesigner_1.readActionType; } });
 Object.defineProperty(exports, "publishFlow", { enumerable: true, get: function () { return flowDesigner_1.publishFlow; } });

package/dist/mcp/registry.d.ts

@@ -7,6 +7,7 @@
  * a client is injected via RegistryDeps (used by tests).
  */
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
 import type { ServiceNowClient } from "../client";
 export declare var TOOL_NAMES: readonly ["create_view", "set_list_layout", "set_form_layout", "set_related_lists", "add_choices_to_field", "flow_view", "action_view", "flow_publish", "flow_copy", "flow_create", "flow_test", "flow_edit"];
@@ -19,6 +20,7 @@ export interface ToolDescriptor {
     name: ToolName;
     description: string;
     shape: z.ZodRawShape;
+    annotations: ToolAnnotations;
     handler: (args: any) => Promise<any>;
 }
 export declare function buildDescriptors(deps?: RegistryDeps): Array<ToolDescriptor>;

package/dist/mcp/registry.js

@@ -39,6 +39,20 @@ exports.TOOL_NAMES = [
     "flow_test",
     "flow_edit"
 ];
+// MCP tool annotations (spec 2025-11-25) — untrusted behavioural hints that let a
+// host parallelize reads and gate writes; never a security boundary. Five presets
+// cover every tool's safety profile:
+//   READ_ONLY                 — no writes; safe to auto-approve and run concurrently.
+//   WRITE_ADDITIVE_IDEMPOTENT — additive write, safe to repeat (idempotent upsert/create).
+//   WRITE_CREATE              — additive write, NOT idempotent (each call mints a new record).
+//   WRITE_OVERWRITE           — destructive but idempotent (prune/overwrite: same end state).
+//   WRITE_EXECUTE             — destructive AND non-idempotent (runs a flow; repeating repeats the effect).
+// openWorldHint is left at its spec default (true) — every tool reaches a ServiceNow instance.
+var READ_ONLY = { readOnlyHint: true };
+var WRITE_ADDITIVE_IDEMPOTENT = { readOnlyHint: false, destructiveHint: false, idempotentHint: true };
+var WRITE_CREATE = { readOnlyHint: false, destructiveHint: false, idempotentHint: false };
+var WRITE_OVERWRITE = { readOnlyHint: false, destructiveHint: true, idempotentHint: true };
+var WRITE_EXECUTE = { readOnlyHint: false, destructiveHint: true, idempotentHint: false };
 function buildDescriptors(deps = {}) {
     function client() {
         return deps.client || (0, client_1.createClient)({});
@@ -46,6 +60,7 @@ function buildDescriptors(deps = {}) {
     return [
         {
             name: "create_view",
+            annotations: WRITE_ADDITIVE_IDEMPOTENT,
             description: "Create a ServiceNow custom view (sys_ui_view). Idempotent — an existing view of the "
                 + "same name is returned unchanged. Every write is captured in the supplied update set.",
             shape: schemas_1.createViewSchema.shape,
@@ -55,6 +70,7 @@ function buildDescriptors(deps = {}) {
         },
         {
             name: "set_list_layout",
+            annotations: WRITE_OVERWRITE,
             description: "Declaratively set a ServiceNow list layout — which columns appear in a list, and their "
                 + "order — for a table + view. Idempotent; prune (default true) removes columns not in "
                 + "the spec; dryRun previews without writing. Writes are captured in the update set.",
@@ -65,6 +81,7 @@ function buildDescriptors(deps = {}) {
         },
         {
             name: "set_form_layout",
+            annotations: WRITE_OVERWRITE,
             description: "Declaratively set a ServiceNow form layout — sections and the fields within them — for "
                 + "a table + view. The first section is the primary section (omit its caption). "
                 + "Idempotent; prune (default true) removes sections/fields not in the spec; dryRun "
@@ -76,6 +93,7 @@ function buildDescriptors(deps = {}) {
         },
         {
             name: "set_related_lists",
+            annotations: WRITE_OVERWRITE,
             description: "Declaratively set which related lists appear on a ServiceNow form for a table + view. "
                 + "Related-list ids are \"<table>.<field>\" or \"REL:<sys_relationship>\". Idempotent; "
                 + "prune (default true); dryRun previews. Writes are captured in the update set.",
@@ -86,6 +104,7 @@ function buildDescriptors(deps = {}) {
         },
         {
             name: "add_choices_to_field",
+            annotations: WRITE_ADDITIVE_IDEMPOTENT,
             description: "Upsert sys_choice values for a ServiceNow table.column and (optionally) flip "
                 + "sys_dictionary.choice so the field renders as a dropdown. Idempotent. Writes are "
                 + "captured in the supplied update set.",
@@ -96,6 +115,7 @@ function buildDescriptors(deps = {}) {
         },
         {
             name: "flow_view",
+            annotations: READ_ONLY,
             description: "Read a ServiceNow Flow Designer flow or subflow's compiled step graph, headless. "
                 + "Returns the ordered, nesting-aware list of action + flow-logic steps plus the flow "
                 + "variables, via GET /api/now/processflow/flow/{sysId}. Read-only. Pass raw:true to "
@@ -108,6 +128,7 @@ function buildDescriptors(deps = {}) {
         },
         {
             name: "action_view",
+            annotations: READ_ONLY,
             description: "Read a ServiceNow Custom Action Type's compiled model (identity, inputs, outputs), "
                 + "headless, via GET /api/now/processflow/action/action_types/{sysId}. Read-only. "
                 + "sysId is the sys_hub_action_type_definition sys_id; scopeSysId is the application "
@@ -120,6 +141,7 @@ function buildDescriptors(deps = {}) {
         },
         {
             name: "flow_publish",
+            annotations: WRITE_OVERWRITE,
             description: "Publish (compile the snapshot of) a ServiceNow Flow Designer flow or subflow via "
                 + "POST /api/now/processflow/flow/{sysId}/snapshot. This is a WRITE that recompiles the "
                 + "flow's current design — use after editing in the Designer. sysId is the sys_hub_flow "
@@ -132,6 +154,7 @@ function buildDescriptors(deps = {}) {
         },
         {
             name: "flow_copy",
+            annotations: WRITE_CREATE,
             description: "Copy a ServiceNow flow/subflow via the Designer's Copy endpoint — a complete, faithful "
                 + "clone created as an INACTIVE DRAFT in the target scope. sourceSysId is the sys_hub_flow "
                 + "to copy; newName is the copy's name; scopeSysId defaults to the source's scope. Publish "
@@ -145,6 +168,7 @@ function buildDescriptors(deps = {}) {
         },
         {
             name: "flow_create",
+            annotations: WRITE_CREATE,
             description: "Create a NEW ServiceNow Flow Designer flow (sys_hub_flow, type=flow) from scratch and "
                 + "PUBLISH it, headless. Mints a fresh flow via POST /processflow/flow, grafts the trigger + "
                 + "action graph from an existing published template flow (templateSysId), then compiles the "
@@ -174,6 +198,7 @@ function buildDescriptors(deps = {}) {
         },
         {
             name: "flow_test",
+            annotations: WRITE_EXECUTE,
             description: "Test or run a ServiceNow flow/subflow. mode='validate' (default) is a safe, read-only "
                 + "pre-flight — checks the flow is published and that supplied inputs match its declared "
                 + "variables; it never runs the flow. mode='execute' actually runs it via the server-side "
@@ -194,6 +219,7 @@ function buildDescriptors(deps = {}) {
         },
         {
             name: "flow_edit",
+            annotations: WRITE_OVERWRITE,
             description: "Edit a ServiceNow flow/subflow in place. Supports rename (name/internalName), description, "
                 + "and patchStepInputs (set named input values on steps by uiId or label). apply=false "
                 + "(default) is a dry-run that returns the diff; apply=true persists the edit (a write). "
@@ -221,7 +247,7 @@ function registerAllTools(server, deps = {}) {
     }
 }
 function registerOne(server, desc) {
-    server.registerTool(desc.name, { description: desc.description, inputSchema: desc.shape }, async function (args) {
+    server.registerTool(desc.name, { description: desc.description, inputSchema: desc.shape, annotations: desc.annotations }, async function (args) {
         try {
             var result = await desc.handler(args);
             return { content: [{ type: "text", text: JSON.stringify(result) }] };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tenonhq/dovetail-servicenow",
-  "version": "0.0.14",
+  "version": "0.0.16",
   "engines": {
     "node": ">=22"
   },