node-autotask 0.21.0 → 0.24.0

package/ARCHITECTURE.md

@@ -64,25 +64,28 @@ proves the mapping op-by-op.
 src/
   index.ts                 # Public API barrel (default + named exports)
   client.ts                # AutotaskClient — top-level facade; wires all resources + operations
-  config.ts                # AutotaskConfig, AutotaskClientOptions, zone catalog + zoneUrl(), validation, defaults
-  http.ts                  # HttpClient — fetch transport, URL/query building, POST/GET query switch,
-                           #   envelope unwrap helpers (pinned to the G1 envelopes)
+  config.ts                # barrel -> config/ (types, zones + zoneUrl(), defaults, profiles, resolve/validation)
+  http.ts                  # barrel -> http/ (HttpClient.ts = fetch transport; request-builders.ts = URL/query
+                           #   building + POST/GET switch; envelope.ts = unwrap helpers pinned to the G1
+                           #   envelopes; retry.ts, breaker-budget.ts, zone.ts, credentials.ts, body.ts, types.ts)
   auth.ts                  # 3-header auth (ApiIntegrationCode/UserName/Secret) + ImpersonationResourceId
                            #   + authenticate() token alternative; credential redaction list
-  errors.ts                # AutotaskError hierarchy + errorFromStatus + vendor error-body parsing
+  errors.ts                # barrel -> errors/ (base.ts hierarchy root, http.ts transport errors, mutation.ts,
+                           #   from-status.ts errorFromStatus, vendor-errors.ts vendor error-body parsing)
   pagination.ts            # Page<T>, cursor-follow walk (nextPageUrl), collectAll(), toArray()
   query.ts                 # Filter builder: 13 operators + and/or grouping, caps, GET<=2048 measurement
   logger.ts                # Logger interface + NoopLogger
-  utils.ts                 # assertRecord, deep-merge of params, identifier helpers, UDF flatten
+  utils/index.ts           # assertRecord, deep-merge of params, identifier helpers, UDF flatten
   capabilities.ts          # GENERATED capability registry (./capabilities) — never hand-edited
   operations/
     index.ts               # ./operations barrel
-    search-across.ts       # searchAcrossResources (cross-resource bounded text search)
-    resolve-any.ts         # resolveAny (cross-resource identifier resolution)
-    invoke.ts              # registry-driven invoke + write governor (G6; MCP projection consumer)
+    searchAcrossResources.ts  # cross-resource bounded text search
+    resolveAny.ts          # cross-resource identifier resolution
+    invoke.ts + invoke/    # registry-driven invoke + write governor (dispatch, validate, modes, wrappers, ...)
+    ...                    # aggregate, fetchMany, fetchByIds, recovery, relationshipMap, probeReachability, ...
   resources/
     index.ts               # Barrel for all resource classes + resources() accessor
-    base.ts                # BaseResource<T> — shared query/get/create/update/delete scaffolding,
+    base.ts + base/        # BaseResource<T> (base/BaseResource.ts; query/mutations/meta/helpers split) — shared query/get/create/update/delete scaffolding,
                            #   entityInfo ops, dry-run scaffolding, scan guards
     companies.ts           # CompaniesResource (top-level entity template — see §12.1)
     company_notes.ts       # CompanyNotesResource (parent-scoped child template — see §12.2)
@@ -99,12 +102,14 @@ src/
 test/
   __fixtures__/            # Mock JSON responses per resource (derived from api-docs.json definitions)
   client.test.ts           # AutotaskClient construction + wiring
-  http.test.ts             # transport, envelopes, error mapping, retries, POST/GET query switch
+  http/                    # one file per concern: transport, envelope, retry, query-builders, hardening,
+                           #   concurrency, logging, mutation-retry
   pagination.test.ts       # cursor-follow walk (nextPageUrl), 1000-page guard
   query.test.ts            # filter builder, caps, GET-length fallback
   config.test.ts           # zone/baseUrl/credentials/pageSize validation
   auth.test.ts             # header shape, impersonation, redaction
   errors.test.ts           # error hierarchy + vendor error-body parsing + item:null semantics
+                           #   (plus errors-*.test.ts and transport-*.test.ts concern files)
   operations/              # searchAcrossResources / resolveAny tests
   resources/
     companies.test.ts      # one spec-per-resource file, alongside each resource
@@ -273,7 +278,7 @@ shape only — deliberately.** Do not "fix" this without reading the reason:
 
 ## 6. Config, validation, and defaults
 
-### `config.ts`
+### `src/config/`
 ```ts
 export type ZoneName =
   | 'pre-release' | 'pre-release-uk' | 'limited-release' | 'limited-release-uk'
@@ -484,7 +489,7 @@ Vendor filter structure (swagger `Filter`, recursive):
 
 ---
 
-## 8. HTTP transport (`http.ts`)
+## 8. HTTP transport (`src/http/`)
 
 - Uses the **native global `fetch`** (native since Node 18; this package's floor is Node >= 24). **Zero runtime dependencies** across the
   whole package.
@@ -571,18 +576,18 @@ export interface RequestOptions {
    auto-unwrap — envelope unwrapping is an explicit per-call decision made by the resource
    layer using the helpers below, pinned to the G1 envelopes.
 10. **Redirects are never followed**: every request is sent with `redirect: 'manual'`
-    (`src/http.ts:911`; the zone-discovery call `:673` likewise, with the same comment). A
+    (`HttpClient.ts`; the zone-discovery call in `src/http/zone.ts` likewise, with the same comment). A
     `3xx` on a normal request cancels the body and throws immediately — no second request
     is made:
     - error: `ResponseRejectedError` with `code: 'REDIRECT_BLOCKED'`, `category: 'policy'`,
       `retryable: false`, `httpStatus` = the 3xx status, and `suggestedAction: 'Check the
-      configured zone/baseUrl; the API does not redirect.'` (`src/errors.ts:135` for the
-      class; the throw site is `src/http.ts:940`).
+      configured zone/baseUrl; the API does not redirect.'` (`ResponseRejectedError` in
+      `src/errors/http.ts`; the throw site is in `src/http/HttpClient.ts`).
     - why: **this SDK attaches credentials to every request**, and a native redirect
       follow re-sends those headers to the redirect target — even cross-origin. Wrapping
       the refusal in a typed error is deliberate (issue #27 shape).
     - the `Location` header is never read, so an attacker-supplied target cannot reach the
-      caller through the message (`test/http.test.ts:530` — "never follows redirects:
+      caller through the message (`test/http/hardening.test.ts` — "never follows redirects:
       sends redirect `'manual'` and refuses a 3xx without a second request" — pins exactly
       one wire call, `redirect: 'manual'`, `code: 'REDIRECT_BLOCKED'`, `retryable: false`,
       and no `evil.example` in the text). Shipped in v0.3.1 (`CHANGELOG.md`); the same
@@ -597,7 +602,7 @@ export interface RequestOptions {
       redirect resolved, and the skill's `manualRedirect` escape hatch (only for endpoints
       whose contract IS a redirect) does not apply here; the builder does not implement one.
 
-### Envelope unwrapping helpers (in `http.ts`, used by `BaseResource`)
+### Envelope unwrapping helpers (in `src/http/envelope.ts`, used by `BaseResource`)
 ```ts
 /** query: expects { items: T[], pageDetails: PagingModel }; validates both present. */
 export function unwrapItems<T>(body: unknown): { items: T[]; pageDetails: PagingModel };
@@ -669,7 +674,7 @@ export function withAuthHeaders(
 
 ---
 
-## 10. Error hierarchy (`errors.ts`)
+## 10. Error hierarchy (`src/errors/`)
 
 ```
 AutotaskError (base; extends Error)
@@ -1000,7 +1005,7 @@ export const NoopLogger: Logger = {};
 
 ## 16. Testing strategy
 
-- **HTTP layer (`http.test.ts`)**: mocked global `fetch` — URL construction, auth headers
+- **HTTP layer (`test/http/*.test.ts`)**: mocked global `fetch` — URL construction, auth headers
   (swagger casing + impersonation), POST/GET query switch (incl. 2048-char `QUERY_TOO_LONG`),
   envelope pass-through, per-envelope unwrap errors, error mapping per status (vendor error
   body formatting), retry/backoff on 429 with `Retry-After`, `Itgenatr005` as retryable
@@ -1022,7 +1027,7 @@ export const NoopLogger: Logger = {};
 - **Coverage gate** (vitest config): lines >= 90 / functions >= 90 / branches >= 80 /
   statements >= 90 (coordinator default from SCOPING F; node-hudu's 97/94/83/97 is the
   stretch target — ratchet at v0.2 once generated-resource tests settle).
-- **Additive-only surface proof**: `test/public-surface.test.ts` compares the live
+- **Additive-only surface proof**: `scripts/public-surface.mjs` (exercised by `test/scripts/generated-gates.test.ts`) compares the live
   exported surface against `test/__fixtures__/public-surface.json`, captured at the G3
   baseline. Removing a baseline name fails the suite; additions are reported, not failed.
 - **Capability gate**: `check-capabilities.mjs` ships with a committed negative fixture
@@ -1036,7 +1041,7 @@ Gates G3–G7 of `.run/CHECKLIST.md`; the per-batch loop never regenerates the w
 until G6 (mechanism in `.run/design/generator-design.md` §10):
 
 1. **G3 — Core + scaffold.** `package.json`/tsconfig/tsup/vitest/eslint; `logger.ts`,
-   `errors.ts`, `auth.ts`, `utils.ts` (no deps) → `config.ts` (+tests) → `http.ts`
+   `errors/`, `auth.ts`, `utils/` (no deps) → `config/` (+tests) → `http/`
    (+tests) → `pagination.ts`, `query.ts` (+tests) → `types/common.ts` →
    `resources/base.ts` → capture the public-surface fixture. Green:
    `npm run typecheck && npm test && npm run build`.
@@ -1258,3 +1263,21 @@ What it ships instead:
   `examples/mcp-server-http.ts` (SSE/streamable-HTTP transport). They are the reference
   implementations the future Autotask MCP server package is built from; the SDK itself
   remains MCP-import-free.
+
+### 19.6 Composite moves (issue #197)
+
+Some vendor entities accept an update of their parent field and silently keep the
+old value (live-probed on ww29: time entries and ticket charges; ticket notes DO
+move on a parent-scoped update). Where the entity can be deleted, a move is a
+composition on the shared engine (`special/_shared/move-engine.ts`): GET-only preview
+-> hard invariants -> twin check -> create (once) -> read-back compare -> source
+re-read -> delete (once), with rollback of the new record on any mismatch or drift.
+The engine returns only for `moved` / `moved_source_absent` / `moved_manual_delete`;
+every other outcome throws a typed `MoveRefusedError` carrying `details.status`
+(`failed` / `partial` / `unknown`). Entities the API cannot move or cannot finish
+deleting hand the person a `manualAction` with an `operations.uiLink` deep link
+(the record where ExecuteCommand supports it, else its parent ticket). The SDK
+authorises nothing (company scope and ownership are the caller's job) and stores
+nothing (the source snapshot is returned). A new resource joins by supplying a
+`MoveSpec` (copy set, invariants, verify list) and one plan row.
+

package/CHANGELOG.md

@@ -7,6 +7,50 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.24.0] - 2026-10-23
+
+The plan hash moves (MINOR) — plan-pinned consumers must re-pin. The 0.24.0 plan hash is `479d7826acf5…` (recorded in `scripts/published-plan-hashes.json` after publish).
+
+### Fixed
+
+- **`tz` on the time-entry `dateWorked` windows picked the wrong day for a zone behind UTC** (live-verified 2026-10-23: `America/Los_Angeles` asked for the 23rd returned the 24th's rows). The vendor stores `dateWorked` as a date-only value at 00:00 UTC, but `tz` converted the local day to UTC instants. `time_entries.postedWithin`, `dateWorkedWindow`, `customRange` and `recentTickets` now treat `from`/`to` as the calendar days they are (`tz` is validated but does not shift them), and the relative windows (`today`, `last7`..`last90`, `lastFullWeek`/`Fortnight`/`Month`/`Quarter`, `yesterday`) use `tz` only to pick which calendar dates apply, sending whole UTC days of them (`last24h` stays rolling). Zones ahead of UTC (e.g. `Australia/Sydney`) return the same rows as before; the `window` field in `postedWithin`/`dateWorkedWindow`/`recentTickets` results now reports whole UTC days instead of zone-converted instants. `billing_items` and `invoices` window ops are unchanged.
+
+### Added (#210)
+
+- `tickets.search(query, { limit, companyID?, includeFields? })`: an optional company scope (a `companyID eq` leaf and-joined server-side with the title `contains`) and a column projection; `searchWithDetail` inherits both. A malformed `companyID`, `includeFields` or an unknown option key is refused before any request (a misspelt `companyId` cannot silently widen the search); `id` is always kept in the projection, and the empty `userDefinedFields: []` the vendor appends to projected rows is dropped (a non-empty one is kept; no projection, no change). Additive; `search` on every other resource is unchanged.
+- `time_entries.recentTickets(from, to, { resourceID, companyID?, tz?, limit? })`: the distinct tickets a resource logged time against in an inclusive `dateWorked` window, with entry count, total hours, last worked date and the ticket's number, title, status, assignee and company, newest first. One bounded time-entry read plus chunked `id in` ticket reads. `companyID` is applied after the join, client-side on the ticket rows (TimeEntry has no `companyID`), so `limit` bounds the entries scanned and other companies' tickets are only counted in `excludedTickets`; the result carries `truncated` in the `postedWithin` sense, plus `entriesWithoutTicket` and `unresolvedTicketIDs` (tickets the read did not return). New plan row (registry now 1217 ops / 854 tools).
+
+## [0.23.0] - 2026-10-21
+
+The plan hash moves (MINOR) — plan-pinned consumers must re-pin. The 0.23.0 plan hash is `95746a69c86d…` (recorded in `scripts/published-plan-hashes.json` after publish).
+
+**W-A3 time-entry zone fact re-scoped (issue #195).** The 2026-10-06 note claimed the vendor "refuses ALL time-entry writes for this API-only user" (UNSATISFIABLE); live `time_entries.create` calls succeeded on 2026-10-21 (pair not recorded; two entries, read back, 1.0 h). The served wording (plan `pointerNotes` + `createGuidance` blocker message/remedy, the four time-entry tool-description overrides, `docs/API.md`) is now a (resource, role) pair-scoped wall: the pair selecting the API-only user's own resource was refused 2026-10-06. The authorised pair set has NOT been re-adjudicated by a live probe.
+- Single source: the wording lives in `capabilities.plan.json`, regenerated into `capabilities.json`, `src/capabilities.ts`, `src/relationships.ts` and the MCP/n8n manifests and catalog.
+- The plan records the success as `zoneFacts.resources.time_entries.liveWrites[]`; new gate clause 18 (`scripts/lib/checks/clause18-zone-fact-liveness.mjs`, test `test/scripts/zone-fact-liveness.test.ts`) fails when a plan zone fact (blocker message/remedy, pointer note) or an `MCP_TOOL_OVERRIDES.json` row asserts a wall (UNSATISFIABLE / refuses all, case-insensitive) stamped before a recorded successful live write of the same op.
+- `scripts/s13b-plan-patch.mjs` no longer writes `pointerNotes` (its archived copy would overwrite the re-stamped rows with older-dated text).
+- Invoke (#196): the query/count field-name refusal now embeds the entity's first 20 field names (`(and N more)` beyond that) in `err.message`, and its suggestedAction points at `operations.fieldCatalog` scoped with `resources: ["<entity>"]`; no extra wire. No plan-hash change.
+
+### Added (wave-1: #197, #198, #200, #201, #202)
+
+- Governed create-verify-delete moves (#197): `time_entries.moveToTicket` and `ticket_charges.moveToTicket` on a shared move engine, because the vendor accepts an update of `ticketID` but silently keeps the old value (live-probed). Dry-run-first (GET-only preview), `confirm` required, typed `MOVE_*` refusals (billed/approved/attachments/too old/twin/closed target), read-back compare, source re-read, rollback, results `moved` / `moved_source_absent` / `moved_manual_delete`, with a `manualAction` carrying an `operations.uiLink` deep link where a person must finish in the UI. New `MoveRefusedError`. Served hints now warn that `ticketID` does not persist on update and that deleting a time entry destroys its attachments; `ticket_notes` update documents that the scoped `ticketID` update moves a note. **Plan hash moves:** `bc4308db3dec…` → `95746a69c86d…` (MINOR; recorded after publish). Registry now 1216 ops / 853 tools.
+- `companies.fullProfile` per-part field projection and `locationLimit` (#200): `fields: { contacts: ['id','firstName'], openTickets: [...] }` serves only the listed fields for a listed part (`IncludeFields` on the wire, then picked client-side); unlisted parts and the no-`fields` call are unchanged. Unknown part key or field name is refused pre-request (zero wire). `locationLimit` (1-500, default 50) replaces the fixed locations cap and drives `locations.capped`. Additive, minor; the plan hash is unchanged (the registry record and generated artifacts carry the new bag keys).
+- `operations.uiLink` (#202): a pure, zero-wire meta op (plus the `buildUiLink` helper) that builds Autotask ExecuteCommand deep links for time entries, tickets (by id or ticket number), tasks, projects, companies, contacts, contracts and configuration items. The `ww<N>` UI host is derived from the client's `webservices<N>` base, never guessed (no link for `pre-release-de`/`-es` or custom hosts unless `host` is passed). Ids are positive safe integers, ticket numbers match `^T\d{8}\.\d{4}$`. **Plan hash moves** (new meta op row): `03a3bf610a85…` → `bc4308db3dec…` (MINOR; recorded after publish). Registry now 1214 ops / 851 tools.
+- `operations.searchAcrossResources` accepts an optional `totalLimit` (#201): caps matches across all resources; resources are searched in request order, each asked for `min(limit, remaining)`, later ones are not queried and are reported in `notSearched`, with `truncated`. Absent `totalLimit` the result is unchanged. `limit` is now documented as per-resource (the old header said "one limit budget"). Additive, minor.
+
+### Changed (wave-1: #198)
+
+- Positional-arity refusal text (#198): dropped the v0.2.0 history aside, and when the surplus arg is a plain object on an op that declares an options bag it adds "options go inside the single `<bag>` object". Message text only; no behaviour or plan change.
+
+## [0.22.0] - 2026-10-21
+
+**Plan `tests[].file` paths refreshed (issues #194, #189).** The plan hash moves (MINOR) — plan-pinned consumers must re-pin. 111 `operations[].tests[]` rows that named pre-split test files now name the file where their title lives; titles are unchanged and the drift gate still resolves by title, so there is no behavioural change.
+- Transport (#184, #190): the per-request deadline timer is now owned by one `try/finally` from the moment it is armed, so a cooldown or breaker refusal, or a throwing `logger.debug` / audit-body redaction, can no longer keep the event loop alive for `timeoutMs`; regression tests spy on `clearTimeout`.
+- Types (#191): the 24 `BaseResource` members that went `private` -> `protected` only to span the query/meta/mutations layers (`cachedGet`, `walkBounded`, `latestWalk`, `unwrapCreateOperation`, ...) are marked `@internal` and stripped from the published `.d.ts` (`stripInternal`); they are not public API and subclasses outside the package cannot rely on them.
+- Tooling (#187, #188, #189): the cache-write-invalidation static guard now scans every `boundedPart`/`readPart`/`windowedPart`/`expandByMonth` caller across all of `src/`; `derive-plan` finds BaseResource methods in `src/resources/base/{query,meta,mutations}.ts`; the test-title lookup ignores comments and `emit(`/`submit(` lookalikes, honours the injected `readFile`, and the capability gate fails a pinned title declared in more than one test file.
+
+- Capability gate (#185): plan `tests[]` rows are now resolved by title across `test/**` (the `file` field is informational); `staleCheck.testFiles`/`testHash` are dropped from the registry. Plan hash unchanged. Test files can be renamed/split freely; the six sprint-coded test files were split by concern.
+- Security (dependabot #182, #183): dev-scope lockfile bumps only — @modelcontextprotocol/server 2.2.0 → 2.3.0 (fixes GHSA-46jr-4wx8-v453, GHSA-jm63-cq47-j5jp, GHSA-rvq5-wwqv-78pq) and vite 8.3.1 → 8.3.4 (fixes GHSA-587h-7wmj-h5pm, GHSA-698v-4r3x-3vcv, GHSA-r825-w8mm-5pxw). No runtime surface change (the package has no runtime dependencies).
+
 ## [0.21.0] - 2026-10-21
 
 **Structured bag properties, core ops in the catalog, op-key error text (issues #162, #163, #164, #177, #178, #179, #180, #181).** The plan hash moves to `baf3e855956e` (MINOR) — plan-pinned consumers must re-pin.

package/MCP_TOOL_CATALOG.json

@@ -1,7 +1,7 @@
 {
   "generatedBy": "scripts/build-tool-catalog.mjs",
-  "generatedAt": "2026-10-20T21:35:51.338Z",
-  "planHash": "baf3e855956ed5450e1efea640845cb0fbc3a3a5a631a6159d4702b8dc726170",
+  "generatedAt": "2026-10-23T03:34:45.957Z",
+  "planHash": "479d7826acf548a8713c6891fe6cc5ea6ebb7c287896c932aac70834860a206f",
   "metaTools": [
     {
       "name": "autotask_catalog",
@@ -43,7 +43,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 363 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 254 today); the 601 readOnlyHint: true tools — including this one — are safe ungated; the 55 destructiveHint: true tools (54 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 363 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 256 today); the 603 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",
@@ -63,7 +63,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 254 tools that require approval (readOnlyHint !== true); the 601 readOnlyHint: true tools are safe ungated, and the 55 destructiveHint: true tools (54 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 256 tools that require approval (readOnlyHint !== true); the 603 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",
@@ -93,7 +93,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 54), 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 55 destructiveHint: true tools that require approval + confirm; approve every tool with readOnlyHint !== true (exactly 254 today); the 601 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 256 today); the 603 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",
@@ -10784,6 +10784,26 @@
       "reachReason": null,
       "boundedAlternative": null
     },
+    {
+      "operation": "time_entries.moveToTicket",
+      "core": false,
+      "tool": "autotask_timeEntry_move_to_ticket",
+      "purpose": "Move a time entry to another ticket. The vendor update does NOT change ticketID, so this creates the record on the target ticket, verifies it, then deletes the source — with refusals for billed/approved/old sources and a twin check against duplicates.",
+      "preferredWhen": "Re-parenting a time entry to another ticket. Not update: the vendor ignores ticketID there. When a move is refused or the source cannot be deleted, the result carries a manualAction with a clickable Autotask UI link (the record itself where the UI supports it, otherwise its parent ticket).",
+      "backingOperation": "time_entries.moveToTicket",
+      "effect": "destructive",
+      "dryRunFirst": true,
+      "confirm": true,
+      "requiredArgs": [
+        "sourceId",
+        "toTicketId"
+      ],
+      "tier": "extended",
+      "reachable": true,
+      "reach": "dedicated tool",
+      "reachReason": null,
+      "boundedAlternative": null
+    },
     {
       "operation": "time_entries.postedWithin",
       "core": false,
@@ -10821,6 +10841,27 @@
       "reachReason": null,
       "boundedAlternative": null
     },
+    {
+      "operation": "time_entries.recentTickets",
+      "core": false,
+      "tool": "autotask_timeEntry_recent_tickets",
+      "purpose": "List the distinct tickets a resource logged time against in an inclusive dateWorked window, with entry count, total hours, last worked date and the ticket's number, title, status, assignee and company.",
+      "preferredWhen": "Finding the ticket a piece of work was logged against, or which tickets a resource has been working on lately. Not for a total over many groups (operations.aggregate) or the raw entries (time_entries.dateWorkedWindow).",
+      "backingOperation": "time_entries.recentTickets",
+      "effect": "read",
+      "dryRunFirst": false,
+      "confirm": false,
+      "requiredArgs": [
+        "from",
+        "to",
+        "opts"
+      ],
+      "tier": "extended",
+      "reachable": true,
+      "reach": "dedicated tool",
+      "reachReason": null,
+      "boundedAlternative": null
+    },
     {
       "operation": "time_entries.resolve",
       "core": false,
@@ -10862,7 +10903,7 @@
       "core": false,
       "tool": "autotask_timeEntry_update",
       "purpose": "Update a time entry.",
-      "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
+      "preferredWhen": "Preferred over create or delete when the record exists and only some fields change. Not for ticketID: the vendor ignores it on update; use time_entries.moveToTicket.",
       "backingOperation": "time_entries.update",
       "effect": "write",
       "dryRunFirst": true,
@@ -20827,6 +20868,26 @@
       "reachReason": "no dedicated tool — the op is still discoverable and invocable by exact name",
       "boundedAlternative": null
     },
+    {
+      "operation": "ticket_charges.moveToTicket",
+      "core": false,
+      "tool": "autotask_ticketCharge_move_to_ticket",
+      "purpose": "Move a ticket charge to another ticket. The vendor update does NOT change ticketID, so this creates the record on the target ticket, verifies it, then deletes the source — with refusals for billed/approved/old sources and a twin check against duplicates.",
+      "preferredWhen": "Re-parenting a ticket charge to another ticket. Not update: the vendor ignores ticketID there. When a move is refused or the source cannot be deleted, the result carries a manualAction with a clickable Autotask UI link (the record itself where the UI supports it, otherwise its parent ticket).",
+      "backingOperation": "ticket_charges.moveToTicket",
+      "effect": "destructive",
+      "dryRunFirst": true,
+      "confirm": true,
+      "requiredArgs": [
+        "sourceId",
+        "toTicketId"
+      ],
+      "tier": "extended",
+      "reachable": true,
+      "reach": "dedicated tool",
+      "reachReason": null,
+      "boundedAlternative": null
+    },
     {
       "operation": "ticket_charges.query",
       "core": false,
@@ -20887,7 +20948,7 @@
       "core": false,
       "tool": "autotask_ticketCharge_update",
       "purpose": "Update a ticket charge.",
-      "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
+      "preferredWhen": "Preferred over create or delete when the record exists and only some fields change. Not for ticketID: use ticket_charges.moveToTicket.",
       "backingOperation": "ticket_charges.update",
       "effect": "write",
       "dryRunFirst": true,
@@ -22281,13 +22342,32 @@
       "reach": "dedicated tool",
       "reachReason": null,
       "boundedAlternative": null
+    },
+    {
+      "operation": "operations.uiLink",
+      "core": false,
+      "tool": "autotask_ui_link",
+      "purpose": "Build a clickable Autotask UI deep link for a record in one ZERO-wire call, e.g. for the time entry or ticket a response is about.",
+      "preferredWhen": "When a person must open a record in the Autotask UI (to finish an action the API will not execute, or to inspect a record). Pure string building — it never confirms the record exists.",
+      "backingOperation": "operations.uiLink",
+      "effect": "read",
+      "dryRunFirst": false,
+      "confirm": false,
+      "requiredArgs": [
+        "input"
+      ],
+      "tier": "extended",
+      "reachable": true,
+      "reach": "dedicated tool",
+      "reachReason": null,
+      "boundedAlternative": null
     }
   ],
   "counts": {
-    "registryOperations": 1213,
+    "registryOperations": 1217,
     "coreOperations": 10,
-    "catalogRows": 1213,
-    "withTool": 850,
+    "catalogRows": 1217,
+    "withTool": 854,
     "readModeOnly": 363,
     "neverExposed": 0,
     "metaTools": 5