node-autotask 0.43.0 → 0.44.0

package/CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.44.0] - 2026-11-01
+
+The capability plan changed (staff resolution and read-contract updates), so this release needs a minor bump.
+
+### Breaking
+
+- **#350:** explicit `walk.maxRows` replaces the ordinary total cap instead of taking its minimum: `{ limit: 100, walk: { maxRows: 2500 } }` can return 2500 rows. Direct explicit walks now honor `names` and client `labels`; pass `names: false` for raw rows. Ordinary bounded query and latest behavior are unchanged.
+- **#351:** self-prefixed dotted UDFs are now refused rather than rewritten to a different tenant field. Use the literal undotted UDF name.
+- **#353:** `operations.resolveAny({ match: 'auto' })` now completes every exact lookup before falling back to the existing bounded cross-resource search. Only clean misses everywhere allow contains matching; exact hits, ambiguity, truncation and faults block fallback. The result identifies `matched: 'exact' | 'contains'` and carries the contains-search payload when used; `limit` is an integer 1..500 and can only narrow the configured resolution scan cap (at most 500); malformed limits refuse before lookup requests. The default exact-only behavior is unchanged.
+- **#354:** untrusted projection now fences nested UDF values and named string arrays, bounds deep/cyclic input and safely copies prototype-like keys. Hosts retain unsafe-character cleaning, length caps and provenance for formatted output; projection does not grant vendor strings any formatting exemption. An unstamped result containing UDF values can now return a projected copy instead of its original reference.
+
+### Added
+
+- **#353:** `operations.resolveStaff` resolves staff by id, email, username or full name. Text lookups require active staff and exclude API users identified by tenant labels unless opted in; numeric id lookups bypass those filters. Candidate limits, truncation and metadata availability are explicit. Text records honor the client’s existing `labels` setting, preserving expanded staff label siblings; projection fences both licenseTypeLabel and userTypeLabel. Numeric-id misses propagate NOT_FOUND; text misses return an empty matches list.
+
+### Fixed
+
+- **#350:** query `walk.maxRows` is the total returned-row cap, independently of the ordinary `limit`/page-size bound, so export-sized walks can return up to the requested total. Scope checks estimate the actual walk, and truncation remains true while a cursor or unserved rows remain. Explicit walks preserve the iterator’s per-vendor-page label budgets and avoid a second labeling pass; ordinary invoked queries keep their per-call budget.
+- **#351:** dotted UDF names, including self-prefixed aliases, are refused before metadata or vendor requests, preserving literal tenant UDF identity.
+- **#352:** self-resource prefixes are normalized consistently in query projection and aggregate group/sum fields, preserving date buckets and parent relations without mutating caller options.
+
 ## [0.43.0] - 2026-10-31
 
 ### Changed

package/MCP_TOOL_CATALOG.json

@@ -1,7 +1,7 @@
 {
   "generatedBy": "scripts/build-tool-catalog.mjs",
-  "generatedAt": "2026-10-31T20:17:42.030Z",
-  "planHash": "5c18b378722a038159564faccee795e7c278f048f30c77d77b5dc27e83ea2dee",
+  "generatedAt": "2026-11-01T01:23:13.336Z",
+  "planHash": "f2b02eb792fd6e2934afab0a48b1c2e338bf741080d15550512c2db5091f4bc5",
   "metaTools": [
     {
       "name": "autotask_catalog",
@@ -51,7 +51,7 @@
     {
       "name": "autotask_read",
       "title": "Read One Registry Operation (read mode)",
-      "description": "Route an effect=read registry operation by its exact name (never fuzzy, never a tool name): the 384 field/entity/UDF-info reads (getEntityInfo/getFieldInfo/getUdfInfo) have no dedicated tool and ride this one, and any read op is routable. For field discovery use operations.fieldCatalog (compact) instead of per-resource getFieldInfo (full dump). Read-only by construction — every op it can route is effect=read (zero mutating requests), and a write or delete op is refused BEFORE any request (cross-mode refusal; the message names the correct tool). Reads have no dry run (a read with dry_run: true is refused). Harness approval policy: approve every tool with readOnlyHint !== true (exactly 267 today); the 635 readOnlyHint: true tools — including this one — are safe ungated; the 57 destructiveHint: true tools (56 dedicated delete tools + autotask_delete) require confirm === the operation key. Migration: autotask_invoke is REPLACED by autotask_read/autotask_write/autotask_delete — update harness config. For query/count ops args[0] is a params object (filter/limit); call autotask_describe first for the exact arg shape and filter grammar. The argument set is CLOSED at the top level: an unknown argument is refused before any request, with a typed error naming the key and the valid keys.",
+      "description": "Route an effect=read registry operation by its exact name (never fuzzy, never a tool name): the 384 field/entity/UDF-info reads (getEntityInfo/getFieldInfo/getUdfInfo) have no dedicated tool and ride this one, and any read op is routable. For field discovery use operations.fieldCatalog (compact) instead of per-resource getFieldInfo (full dump). Read-only by construction — every op it can route is effect=read (zero mutating requests), and a write or delete op is refused BEFORE any request (cross-mode refusal; the message names the correct tool). Reads have no dry run (a read with dry_run: true is refused). Harness approval policy: approve every tool with readOnlyHint !== true (exactly 267 today); the 636 readOnlyHint: true tools — including this one — are safe ungated; the 57 destructiveHint: true tools (56 dedicated delete tools + autotask_delete) require confirm === the operation key. Migration: autotask_invoke is REPLACED by autotask_read/autotask_write/autotask_delete — update harness config. For query/count ops args[0] is a params object (filter/limit); call autotask_describe first for the exact arg shape and filter grammar. The argument set is CLOSED at the top level: an unknown argument is refused before any request, with a typed error naming the key and the valid keys.",
       "input": {
         "operation": {
           "type": "string",
@@ -71,7 +71,7 @@
     {
       "name": "autotask_write",
       "title": "Write One Registry Operation (write mode)",
-      "description": "Route an effect=write registry operation by its exact name (never fuzzy, never a tool name), dry-run-first: the first call always travels dry_run: true (the pinned DryRunResult envelope, simulated: true — the mutating request is never issued); pass dry_run: false to apply. A read or delete op is refused BEFORE any request (cross-mode refusal; the message names the correct tool). The 3 approval-gated writes (configuration_items.moveConfigurationItem, contacts.moveToCompany, resources.transferOwnership) additionally require confirm === the operation key, in BOTH dry-run and apply mode. Harness approval policy: this tool is one of the 267 tools that require approval (readOnlyHint !== true); the 635 readOnlyHint: true tools are safe ungated, and the 57 destructiveHint: true tools (56 dedicated delete tools + autotask_delete) require confirm === the operation key. Migration: autotask_invoke is REPLACED by autotask_read/autotask_write/autotask_delete — update harness config. For query/count ops args[0] is a params object (filter/limit); call autotask_describe first for the exact arg shape and filter grammar. The argument set is CLOSED at the top level: an unknown argument is refused before any request, with a typed error naming the key and the valid keys.",
+      "description": "Route an effect=write registry operation by its exact name (never fuzzy, never a tool name), dry-run-first: the first call always travels dry_run: true (the pinned DryRunResult envelope, simulated: true — the mutating request is never issued); pass dry_run: false to apply. A read or delete op is refused BEFORE any request (cross-mode refusal; the message names the correct tool). The 3 approval-gated writes (configuration_items.moveConfigurationItem, contacts.moveToCompany, resources.transferOwnership) additionally require confirm === the operation key, in BOTH dry-run and apply mode. Harness approval policy: this tool is one of the 267 tools that require approval (readOnlyHint !== true); the 636 readOnlyHint: true tools are safe ungated, and the 57 destructiveHint: true tools (56 dedicated delete tools + autotask_delete) require confirm === the operation key. Migration: autotask_invoke is REPLACED by autotask_read/autotask_write/autotask_delete — update harness config. For query/count ops args[0] is a params object (filter/limit); call autotask_describe first for the exact arg shape and filter grammar. The argument set is CLOSED at the top level: an unknown argument is refused before any request, with a typed error naming the key and the valid keys.",
       "input": {
         "operation": {
           "type": "string",
@@ -101,7 +101,7 @@
     {
       "name": "autotask_delete",
       "title": "Delete One Registry Operation (delete mode)",
-      "description": "Route an effect=destructive (delete) registry operation by its exact name (never fuzzy, never a tool name), dry-run-first: the first call always travels dry_run: true (the pinned DryRunResult envelope, simulated: true); pass dry_run: false to apply. confirm === the operation key is REQUIRED for every delete (all 56), in BOTH dry-run and apply mode — the deliberate act is the call, not the delete. A read or write op is refused BEFORE any request (cross-mode refusal; the message names the correct tool). Harness approval policy: this tool is one of the 57 destructiveHint: true tools that require approval + confirm; approve every tool with readOnlyHint !== true (exactly 267 today); the 635 readOnlyHint: true tools are safe ungated. Migration: autotask_invoke is REPLACED by autotask_read/autotask_write/autotask_delete — update harness config. The argument set is CLOSED at the top level: an unknown argument is refused before any request, with a typed error naming the key and the valid keys.",
+      "description": "Route an effect=destructive (delete) registry operation by its exact name (never fuzzy, never a tool name), dry-run-first: the first call always travels dry_run: true (the pinned DryRunResult envelope, simulated: true); pass dry_run: false to apply. confirm === the operation key is REQUIRED for every delete (all 56), in BOTH dry-run and apply mode — the deliberate act is the call, not the delete. A read or write op is refused BEFORE any request (cross-mode refusal; the message names the correct tool). Harness approval policy: this tool is one of the 57 destructiveHint: true tools that require approval + confirm; approve every tool with readOnlyHint !== true (exactly 267 today); the 636 readOnlyHint: true tools are safe ungated. Migration: autotask_invoke is REPLACED by autotask_read/autotask_write/autotask_delete — update harness config. The argument set is CLOSED at the top level: an unknown argument is refused before any request, with a typed error naming the key and the valid keys.",
       "input": {
         "operation": {
           "type": "string",
@@ -23511,6 +23511,25 @@
       "reachReason": null,
       "boundedAlternative": null
     },
+    {
+      "operation": "operations.resolveStaff",
+      "core": false,
+      "tool": "autotask_resolve_staff",
+      "purpose": "Resolve staff with tenant-labelled API-user exclusions and honest metadata state.",
+      "preferredWhen": "Resolve an owner or technician by email, username or name; use numeric id for an exact Resource fetch regardless of active/licence status.",
+      "backingOperation": "operations.resolveStaff",
+      "effect": "read",
+      "dryRunFirst": false,
+      "confirm": false,
+      "requiredArgs": [
+        "identifier"
+      ],
+      "tier": "extended",
+      "reachable": true,
+      "reach": "dedicated tool",
+      "reachReason": null,
+      "boundedAlternative": null
+    },
     {
       "operation": "operations.revenueRollup",
       "core": false,
@@ -23588,10 +23607,10 @@
     }
   ],
   "counts": {
-    "registryOperations": 1281,
+    "registryOperations": 1282,
     "coreOperations": 10,
-    "catalogRows": 1281,
-    "withTool": 897,
+    "catalogRows": 1282,
+    "withTool": 898,
     "readModeOnly": 384,
     "neverExposed": 0,
     "metaTools": 5