iit-mcp-autotask 0.35.1 → 0.38.0

package/README.md

@@ -8,10 +8,10 @@ context into one call, a generic read layer for the long tail, one result envelo
 packaged playbooks, strong security boundaries, and predictable per-tenant in-process state (pooled
 client + SDK-owned TTL caches).
 
-> **Package status (2026-10-24):** the runtime dependency `node-autotask` is published to public npm
-> at `0.25.0`; the committed `pnpm-lock.yaml` pins that
+> **Package status (2026-10-29):** the runtime dependency `node-autotask` is published to public npm
+> at `0.38.0`; the committed `pnpm-lock.yaml` pins that
 > release with its integrity hash, so installs resolve deterministically. The dependency is always npm
-> (node-autotask pinned exactly at `0.25.0`) — never a `file:`, `git:`, `link:` or workspace reference
+> (node-autotask pinned exactly at `0.38.0`) — never a `file:`, `git:`, `link:` or workspace reference
 > to a local checkout.
 
 > **0.6.0 is a breaking release** (unreleased): tool names, result shapes and configuration all
@@ -19,15 +19,16 @@ client + SDK-owned TTL caches).
 
 ## Tool surface
 
-The **core** toolset (12 tools) is always served; `AUTOTASK_TOOLSETS` adds `service`, `records` and
-`finance` (or `all`, 19 tools); the operator profile adds two. The whole tool surface (21 tools) is
-listed below. Every other operation in the SDK's 1,216-operation registry stays
+The **core** toolset (10 tools) is always served; `AUTOTASK_TOOLSETS` adds `service`, `records` and
+`finance` (or `all`, 17 tools); the operator profile adds two. The whole tool surface (19 tools) is
+listed below. Every other operation in the SDK's 1,281-operation registry stays
 reachable through the generic layer: `autotask_catalog` finds the key, `autotask_describe` serves
-its contract, `autotask_read` runs it.
+its contract (slim by default: transport and retry detail dropped, long text cut, the first two
+examples; `full: true` serves the complete record, `summary: true` about 2 KB), `autotask_read` runs it.
 
 | Toolset | Tools |
 |---------|-------|
-| core (always) | `autotask_guide` · `autotask_catalog` · `autotask_describe` · `autotask_read` · `autotask_resolve` · `autotask_query` · `autotask_aggregate` · `autotask_fetch_many` · `autotask_tenant_status` · `autotask_ticket_full_context` · `autotask_company_full_profile` · `autotask_resource_workload` |
+| core (always) | `autotask_guide` · `autotask_catalog` · `autotask_describe` · `autotask_read` · `autotask_resolve` · `autotask_query` · `autotask_tenant_status` · `autotask_ticket_full_context` · `autotask_company_full_profile` · `autotask_resource_workload` |
 | `service` | `autotask_project_get_context` · `autotask_service_call_full_profile` |
 | `records` | `autotask_contact_full_profile` · `autotask_configuration_item_profile` · `autotask_contract_full_profile` |
 | `finance` | `autotask_quote_get` · `autotask_invoice_get` (`format`: `record`, `html`, `xml`, `pdf`) |
@@ -35,12 +36,24 @@ its contract, `autotask_read` runs it.
 
 - `autotask_resolve` turns any identifier into a record: an id or name, `by: "ticket_number"`,
   `"serial"` or `"email"`, in one `resource` or swept across the five workflow resources;
-  `match: "contains"` for companies, tickets (title) or a sweep. `resource: "resources"` finds staff by
+  the default `match: "auto"` tries exact, then contains on a miss for companies, tickets (title) or a
+  sweep (one hit: `ok` with `matched: "contains"`; several: `ambiguous`), `match: "exact"` has no
+  fallback, `match: "contains"` searches only. `resource: "resources"` finds staff by
   email, user name or name (active only; API users, which carry their owner's email, are excluded unless
   `include_api_users: true`; `by: "email"` narrows to the email field; a numeric identifier is looked up
-  as a Resource id); compact rows carry `apiUser` and the licence label when the tenant's labels tell it, never an email. Every match carries `ref`, its human reference. A sweep returns compact matches (`resource`, `ref`, `id`, the human fields) unless `expand: true` (the full record under `record`); `limit` caps the TOTAL matches across resources (resource order, then the SDK's order) and a contains sweep reports `truncated` and per-resource `counts {returned, found}`.
-- `autotask_query` is the bounded filtered list over `resource`: `tickets`, `time_entries`,
-  `service_calls`, `contracts`, `time_off_requests` (limit default 50, max 2500). The served filter
+  as a Resource id); compact rows carry `apiUser` and the licence label when the tenant's labels tell it, never an email. Every match carries `ref`, its human reference, as safe text: control and markup characters (`< > { } [ ] \` " | \\`) dropped, whitespace collapsed, at most 80 characters (a cut ends with `…`), never wrapped; still vendor-authored data (#230). A sweep returns compact matches (`resource`, `ref`, `id`, the human fields) unless `expand: true` (the record under `record`, without its `[REDACTED]`, null and empty fields; `expand: "full"` keeps them); `limit` caps the TOTAL matches across resources (resource order, then the SDK's order) and a contains sweep reports `truncated` and per-resource `counts {returned, found}`.
+- `autotask_query` is the bounded filtered list over `resource`: any resource with a
+  `<resource>.query` read (`tickets`, `time_entries`, `service_calls`, `contracts`,
+  `time_off_requests`, `companies`, `billing_items`, ...; limit default 50, max 2500). With
+  `group_by`, `sum` or `count: true` it answers totals instead of rows (the SDK's
+  `operations.aggregate`; `top` 1-100 groups, `limit` up to 2,500 scanned rows; `hasMore` /
+  `groupsTruncated` mean partial). Records by id: `filter: [{field: "id", op: "in", value: "1,2,3"}]`
+  (`in` / `notIn` take an array or a comma string). Time entries have no `companyID`: the relation
+  filter `{field: "ticket.companyID", op: "eq", value: "<id>"}` (also `task.<field>`; `project.<field>`
+  where the entity has the FK) scopes them through one parent read of at most 300 ids (more is a typed
+  refusal; no parent match is an empty result with a `relationNote`), in rows, counts and totals.
+  The separate `autotask_aggregate` and `autotask_fetch_many` tools are removed (#228, 0.37.0); a
+  mixed-resource batch by id is `autotask_read` `operations.fetchByIds`. The served filter
   schema declares each condition as `{field, op, value}` strings, so a client that builds one type
   per array column writes `"29"`, `"true"`, `"2026-10-22"`; numbers, `in` arrays and and/or groups are
   still accepted and passed through unchanged.
@@ -51,11 +64,10 @@ its contract, `autotask_read` runs it.
   fields, because form-filling clients (Copilot Studio) fill every optional input they are shown. A
   client that cannot send a mixed-type array asks for a time entry window over a resource with
   `autotask_query` `time_entries` (`resourceID` eq, `dateWorked` gte/lte, every value a string: the
-  served filter schema types `value` as a string). `autotask_read` and `autotask_fetch_many` answer ONE envelope (the next minor,
+  served filter schema types `value` as a string). `autotask_read` answers ONE envelope (the next minor,
   breaking): `data = { results: Slot[], ok, failed, budget?, budgetWarning? }`, an array in input
   order even for a single read (`data.results[0].result`). A slot is `{ ok: true, operation, result,
-  windowNote?, scopeNote? }` or `{ ok: false, operation, error }`; fetch_many slots also echo `resource` and `id`
-  (`operation` is `<resource>.get`; a miss is `ok: false` with `NOT_FOUND`). A single read that fails
+  windowNote?, scopeNote? }` or `{ ok: false, operation, error }`. A single read that fails
   still answers the whole-call error envelope.
 - `autotask_guide` serves the packaged playbooks — the server's skill layer (below).
 
@@ -96,7 +108,7 @@ part miss never fails the call (typed `absent`); only a missing root record fail
 (`src/tools/reasons.ts`). Vendor free text is wrapped in `<untrusted_content>`,
 stripped of every control (except newline and tab), format and default-ignorable character (bidi,
 zero-width, tag characters, variation selectors) and capped at 500 characters
-(`truncated: true` on the envelope); the wrapper is the injection control — the angle-bracket
+(`textCapped: true` on the envelope; row cuts are `hasMore`); the wrapper is the injection control — the angle-bracket
 escape earlier builds added was removed in 0.9.0 (issue #70): it was pure cost for LLM consumers
 and broke read-modify-write round-trips, so wrapped text carries raw `&`/`<`/`>` and is data,
 never instructions. User-defined field values get the same treatment; `output_path` files keep the
@@ -336,18 +348,15 @@ decoded bytes for `pdf`) under the same root rules — never a JSON envelope, ne
 to the exact vendor markup); a `pdf` past the vendor 1 MiB inline limit is truncated and carries no
 data (and no file).
 
-**`enrich` resolves FK ids to names in the same call** (issue #67): `enrich: ['company',
-'resource', 'assignedResource', 'ticket']` — the keys are per-resource (a key that does not apply to
-the resource is refused pre-dispatch, zero wire) — fetches the referenced records per key — a
-`fetchByIds` batch of 250 distinct ids, then one authority read per id the batch did not return
-(query-blind resources are read one by one) — and lands `<key>Name` in each row (`companyName`, the
-joined `firstName middleName lastName`, `ticketNumber`). A key with more than 500 distinct ids is
-skipped (its rows are null) and named in the summary; `include_fields` never blinds it — the server
-adds the keys' FK ids to the outgoing projection; a miss (an id the vendor does not resolve) is a
-`null` on that row only. There is no `contact` key in this release: the SDK's bulk id read refuses
-parent-scoped resources (`contacts` is one — its get needs (parentId, id)) before the request,
-after the query wire is spent; contact names stay reachable via `autotask_resolve` and the
-composite tools, and a scoped contact read is a follow-up.
+**Labels come with the rows** (node-autotask 0.38.0, #227): query rows, `group_by` keys and
+fetched records carry SDK label siblings by default: picklists as `<field>Label` (`statusLabel`),
+ids as `<field>Name` (`companyIDName`, `contractIDName`, `resourceIDName`, `ticketIDName`, ...;
+`assignedResourceName` stays as a deprecated alias for one release). Each name is capped at 200
+characters and wrapped once as untrusted content; since node-autotask 0.39.0 the sibling key is always present, `null` when the id is null, 0 or unresolved (or the picklist value is null); a `names` note says when
+the SDK's cold-read cap left something unlabelled; `names: false` turns labels off. The server-side
+`enrich` parameter is removed (0.37.0): a call that still sends it is refused as an unknown input; read
+the SDK label instead (`companyIDName` for the old `companyName`, `resourceIDName` for `resourceName`,
+`ticketIDName` for `ticketName`).
 
 ## Transports
 
@@ -763,7 +772,7 @@ independent review with its resolutions, [`docs/reviews/0.6.0.md`](docs/reviews/
 
 ## SDK dependency
 
-`iit-mcp-autotask` depends on **`node-autotask` from npm at exactly `0.25.0`** (an exact pin —
+`iit-mcp-autotask` depends on **`node-autotask` from npm at exactly `0.38.0`** (an exact pin —
 no range operator; subpaths `.` / `/capabilities` / `/operations` / `/resources` / `/types` /
 `/pool`) — the only **vendor** dependency; the other two runtime dependencies are
 `@modelcontextprotocol/server` (the MCP framework) and `zod` (schema validation). It never
@@ -773,7 +782,7 @@ user — the published tarball ships no lockfile) must resolve to the release th
 reviewed against, or the plan-hash boot check refuses to start.
 
 **Publishing `node-autotask` is the maintainer's action, done manually.** It is published on the
-public registry at `0.25.0` (published 2026-10-23); the
+public registry at `0.37.0` (published 2026-10-28 UTC); the
 exact pin and the committed `pnpm-lock.yaml` (with `pnpm-workspace.yaml`) pin the real published
 tarball with its integrity hash, so installs resolve to exactly that release — the lockfile
 freezes the pnpm/git/Docker paths, the pin freezes the npm/npx paths. The docs are written against this
@@ -867,9 +876,9 @@ physical assets (Autotask models them as Configuration Items — covered).
 
 | # | Item | Status |
 |---|------|--------|
-| B1 | **Project phase & task lists** (W7 sub-capability): no `project_tasks`/`project_phases` operations in the SDK's 1,216-op registry. W7 ships with project status + context; phase/task lists excluded and documented. Classification (SDK gap vs vendor API-version limit) is decided by recon's spec-side check (A2). | blocked — documented |
+| B1 | **Project phase & task lists** (W7 sub-capability): no `project_tasks`/`project_phases` operations in the SDK's 1,281-op registry. W7 ships with project status + context; phase/task lists excluded and documented. Classification (SDK gap vs vendor API-version limit) is decided by recon's spec-side check (A2). | blocked — documented |
 | B2 | **Time-entry writes on ww29/australia-nz for API-only users**: vendor 500 (live-verified). Time-entry creation works where the API user is a real resource, through the operator profile (`log-time-entry`); on ww29 the write is classified `failed` (a 500 with a vendor `errors[]` body), never `unknown`. | zone limitation |
-| B3 | **`time_entries.getPosted`/`getUnposted`: the zone's TimeEntry entity has no `postedDate`**, so SDK 0.31 and earlier 500ed (and `postedWithin`/`dateWorkedWindow` silently counted every entry unposted). SDK 0.32.0 derives posted state from a `billing_items.timeEntryID` join and returns `{ items, hasMore, window, approvedCount, unapprovedCount }` (optional date-only `dateFrom`/`dateTo`; no dates reads only the first 500 entries). Needs BillingItems read permission (one extra request per call); `approvedCount`/`unapprovedCount` are not posted state. Reachable via the generic layer. | resolved in SDK 0.32.0 (not re-verified live) |
+| B3 | **`time_entries.getPosted`/`getUnposted`: the zone's TimeEntry entity has no `postedDate`**, so SDK 0.31 and earlier 500ed (and `postedWithin`/`dateWorkedWindow` silently counted every entry unposted). SDK 0.32.0 derives posted state from a `billing_items.timeEntryID` join and returns `{ items, hasMore, window, approvedCount, unapprovedCount }` (optional date-only `dateFrom`/`dateTo`; no dates reads only the first 500 entries). Needs BillingItems read permission (one extra request per call); `approvedCount`/`unapprovedCount` are not posted state. SDK 0.37.0 adds `cursor`/`nextCursor` (page past 500 entries), `unconfirmed` (entries whose posted state is unknown, kept out of both counts) and `countOnly: true` on the four posted-state ops. Reachable via the generic layer. | resolved in SDK 0.32.0 (not re-verified live) |
 | B4 | **CI create on tenants without products** (ww29 product wall: `products.count = 0`): `configuration_items.create` requires an existing `productID`. No dedicated CI-create in v1; the wall is documented on the generic side. | zone limitation |
 | B5 | **Blind count/query surfaces on ww29** (companies not owned by the caller; tickets): count/query return 0/empty even when data exists. Not fixable client-side; the surface carries the typed blind-surface sentinel — `get(id)`/full-profile are the authorities. | zone limitation |
 | B6 | **`node-autotask` npm publish**: the Phase-C install gate re-checks the registry; if still 404 the build pauses and escalates (SCOPING-resolved: the user publishes — no git/file dependency fallback). | open — user action |

package/capabilities.json

@@ -3,10 +3,10 @@
   "domain": "autotask",
   "description": "Machine-readable capability catalogue for iit-mcp-autotask: the tools the server can serve, with the toolset and the lowest profile that serves each. Everything else in the registry is reachable through the generic layer (autotask_catalog / autotask_describe / autotask_read) and documented in docs/capability-matrix.md. Generated from src/tools/surface.ts by scripts/build-capabilities.mjs.",
   "exposedToolCount": {
-    "readonlyCore": 12,
-    "readonlyAll": 19,
-    "operatorCore": 14,
-    "operatorAll": 21
+    "readonlyCore": 10,
+    "readonlyAll": 17,
+    "operatorCore": 12,
+    "operatorAll": 19
   },
   "profiles": {
     "readonly": {
@@ -24,8 +24,6 @@
       "autotask_read",
       "autotask_resolve",
       "autotask_query",
-      "autotask_aggregate",
-      "autotask_fetch_many",
       "autotask_tenant_status",
       "autotask_ticket_full_context",
       "autotask_company_full_profile",
@@ -69,7 +67,7 @@
     },
     {
       "id": "autotask.platform.catalog",
-      "description": "Find the exact operation key for anything without a dedicated tool: ranked search (q) over the 1,216 registry operations, with effect and whether this deployment serves it. No vendor call.",
+      "description": "Find the exact operation key for anything without a dedicated tool: ranked search (q) over the 1,281 registry operations, with effect and whether this deployment serves it. No vendor call.",
       "mcpPrimitive": "tool",
       "toolName": "autotask_catalog",
       "type": "read",
@@ -101,7 +99,7 @@
     },
     {
       "id": "autotask.generic.read",
-      "description": "Run reads by exact registry key, or up to 10 in one call: unbilled work, profitability and margin, SLA health. *.query: 50 rows; scope by company/contract ids (unscoped = tenant walk); roll-ups: autotask_aggregate; slim: includeFields, noteChars.",
+      "description": "Run reads by exact registry key, or up to 10 in one call: unbilled work, profitability and margin, SLA health. *.query: 50 rows; scope by company/contract ids (unscoped = tenant walk); totals: autotask_query group_by; slim: includeFields, noteChars.",
       "mcpPrimitive": "tool",
       "toolName": "autotask_read",
       "type": "read",
@@ -117,7 +115,7 @@
     },
     {
       "id": "autotask.discovery.resolve",
-      "description": "Find the record behind an identifier: id or name, ticket number, CI serial, contact email (by), staff by email, user name or name (resource resources, include_api_users); one resource or a sweep. Exact by default; contains: companies, tickets, sweep.",
+      "description": "Find the record for an identifier: id or name, ticket number, CI serial, contact email (by), staff by email, user name or name (resource resources, include_api_users); one resource or a sweep. Exact, then contains on a miss.",
       "mcpPrimitive": "tool",
       "toolName": "autotask_resolve",
       "type": "read",
@@ -133,45 +131,13 @@
     },
     {
       "id": "autotask.discovery.query",
-      "description": "List records with a filter: tickets, time entries, service calls, contracts or time-off requests. Scope by company/contract ids (unscoped = tenant walk); roll-ups: autotask_aggregate. default 50, max 2500; latest N. Slim: include_fields, note_chars.",
+      "description": "List records or totals with a filter: tickets, time entries, service calls, contracts, time off, more. Totals, no rows: group_by, sum, count (hours logged by ticket, how many match). By id: id in. Scope by company ids (unscoped = tenant walk).",
       "mcpPrimitive": "tool",
       "toolName": "autotask_query",
       "type": "read",
       "toolset": "core",
       "profile": "readonly",
-      "backingOperation": "tickets.query | time_entries.query | service_calls.query | contracts.query | time_off_requests.query",
-      "annotations": {
-        "readOnly": true,
-        "idempotent": true,
-        "destructive": false,
-        "openWorld": true
-      }
-    },
-    {
-      "id": "autotask.core.aggregate",
-      "description": "Totals, counts and group-by sums (hours by ticket) over any <resource>.query table without reading rows. No groupBy or sum = one count call. hasMore or groupsTruncated = a partial answer, never a tenant total.",
-      "mcpPrimitive": "tool",
-      "toolName": "autotask_aggregate",
-      "type": "read",
-      "toolset": "core",
-      "profile": "readonly",
-      "backingOperation": "operations.aggregate",
-      "annotations": {
-        "readOnly": true,
-        "idempotent": true,
-        "destructive": false,
-        "openWorld": true
-      }
-    },
-    {
-      "id": "autotask.discovery.fetch_many",
-      "description": "Fetch up to 500 records by numeric id across mixed resources in one call: items: [{resource, id, fields?}]. Answers data.results[{ok, operation, result|error}], ok, failed (same as autotask_read); a miss is a typed NOT_FOUND slot.",
-      "mcpPrimitive": "tool",
-      "toolName": "autotask_fetch_many",
-      "type": "read",
-      "toolset": "core",
-      "profile": "readonly",
-      "backingOperation": "operations.fetchByIds",
+      "backingOperation": "tickets.query | time_entries.query | service_calls.query | contracts.query | time_off_requests.query | operations.aggregate",
       "annotations": {
         "readOnly": true,
         "idempotent": true,
@@ -395,7 +361,7 @@
       "autotask_describe",
       "autotask_read"
     ],
-    "backingRegistryOperations": 1280,
+    "backingRegistryOperations": 1281,
     "note": "autotask_catalog finds the exact operation key (ranked search), autotask_describe serves its contract, autotask_read runs any effect=read key. Writes go through the operator profile (autotask_write then autotask_apply); authenticate.* is never served."
   },
   "schemas": {}

package/dist/mocks/fixture-ops.d.ts

@@ -20,7 +20,7 @@ import type { InvokeOptions } from 'node-autotask/operations';
 import type { HourlyBudget, QueryWalkParams, QueryWalkResult, ToolClient, ToolOps } from '../tools/context.js';
 /** One recorded ops invocation (the handler-driven vendor-call view). */
 export interface OpCall {
-    method: 'invokeRead' | 'invokeWrite' | 'invokeDelete' | 'resolveAny' | 'searchAcrossResources' | 'fetchMany' | 'fetchByIds' | 'relationshipMap' | 'queryWalk' | 'hourlyBudget';
+    method: 'invokeRead' | 'invokeWrite' | 'invokeDelete' | 'resolveAny' | 'searchAcrossResources' | 'relationshipMap' | 'queryWalk' | 'hourlyBudget';
     client: ToolClient;
     /** The operation key (invoke*) or the helper's primary argument. */
     target: string;
@@ -35,7 +35,7 @@ export type FixtureBehaviour = {
     kind: 'error';
     error: () => unknown;
 }
-/** The helper-shaped outcomes (resolveAny / searchAcrossResources / fetchMany). */
+/** The helper-shaped outcomes (resolveAny / searchAcrossResources). */
  | {
     kind: 'helper';
     value: () => unknown;
@@ -83,20 +83,6 @@ export declare class MockToolOps implements ToolOps {
         resources?: readonly string[];
         limit?: number;
     }, signal?: AbortSignal) => Promise<unknown>;
-    fetchMany: (client: ToolClient, items: readonly Readonly<{
-        resource: string;
-        id: number;
-        fields?: string[];
-    }>[], opts?: {
-        maxItems?: number;
-    }, signal?: AbortSignal) => Promise<unknown>;
-    fetchByIds: (client: ToolClient, items: readonly Readonly<{
-        resource: string;
-        id: number | string;
-        fields?: string[];
-    }>[], opts?: {
-        maxItems?: number;
-    }, signal?: AbortSignal) => Promise<unknown>;
     relationshipMap: (client: ToolClient, resourceKey: string) => Promise<unknown>;
     /** The `output_path` walk (target = the query operation key). */
     queryWalk: (client: ToolClient, operation: string, params: QueryWalkParams, maxRows: number, signal?: AbortSignal) => Promise<QueryWalkResult | undefined>;

package/dist/mocks/fixture-ops.js

@@ -108,8 +108,6 @@ export class MockToolOps {
     invokeDelete = (client, operation, args, opts, signal) => this.answer(client, 'invokeDelete', operation, args, opts, signal);
     resolveAny = (client, identifier, opts, signal) => this.answer(client, 'resolveAny', 'resolveAny', [identifier, opts?.resources], undefined, signal);
     searchAcrossResources = (client, query, opts, signal) => this.answer(client, 'searchAcrossResources', 'searchAcrossResources', [query, opts?.resources, opts?.limit], undefined, signal);
-    fetchMany = (client, items, opts, signal) => this.answer(client, 'fetchMany', 'fetchMany', [items, opts?.maxItems], undefined, signal);
-    fetchByIds = (client, items, opts, signal) => this.answer(client, 'fetchByIds', 'fetchByIds', [items, opts?.maxItems], undefined, signal);
     relationshipMap = (client, resourceKey) => this.answer(client, 'relationshipMap', 'relationshipMap', [resourceKey], undefined, undefined);
     /** The `output_path` walk (target = the query operation key). */
     queryWalk = (client, operation, params, maxRows, signal) => this.answer(client, 'queryWalk', operation, [params, maxRows], undefined, signal);

package/dist/tools/aggregate.d.ts

@@ -1,4 +1,16 @@
 import type { ToolContext } from './context.js';
-import type { BuiltTool } from './surface.js';
-/** `autotask_aggregate`: counts, totals and group-by sums over one `<resource>.query` surface. */
-export declare function buildAggregate(ctx: ToolContext): BuiltTool;
+import { type ToolReturn } from './results.js';
+/** The SDK aggregate opts this server passes (the SDK's own names). */
+export interface AggregateOpts {
+    groupBy?: string[];
+    sum?: string[];
+    top?: number;
+    limit?: number;
+    /** false: no label siblings on the group keys (SDK default on). */
+    names?: boolean;
+}
+/**
+ * Counts, totals and group-by sums over one `<resource>.query` surface: `autotask_query` with
+ * group_by / sum / count (#228). `extra` rides the data.
+ */
+export declare function runAggregate(ctx: ToolContext, operation: string, rawFilter: unknown, opts: AggregateOpts, signal: AbortSignal | undefined, extra?: Record<string, unknown>): Promise<ToolReturn>;

package/dist/tools/aggregate.js

@@ -1,21 +1,22 @@
 /**
- * tools/aggregate.ts — `autotask_aggregate` (#197): a thin wrapper over the SDK's
- * `operations.aggregate`, served in core so a roll-up question (totals, counts, group-by sums) is one
- * call to a tool the model sees, not a ~50 KB discovery trip through catalog, describe and read.
+ * tools/aggregate.ts — the totals mode of `autotask_query` (`group_by` / `sum` / `count`; #197, #228):
+ * a thin wrapper over the SDK's `operations.aggregate`, so a roll-up question (totals, counts, group-by
+ * sums) is one call to a core tool, not a ~50 KB discovery trip through catalog, describe and read.
  *
  * Nothing is reimplemented: the SDK validates the operation, the field names and the caps (top 1-100,
  * limit at most 2,500), folds the rows and reports its own truncation honesty (`hasMore`,
- * `groupsTruncated`, `totalScanned`, `blind`); the tool passes the answer through unchanged. What the
- * tool adds is the gates every read passes (the deployment policy on both the helper and the target
- * surface, the inbound untrusted-wrapper strip, the filter shape) and the untrusted marking of the
- * answer by the TARGET resource's field stamps, the same list `autotask_read` of `<resource>.query` uses.
+ * `groupsTruncated`, `totalScanned`, `blind`); the answer passes through unchanged. What this adds is
+ * the gates every read passes (the deployment policy on both the helper and the target surface, the
+ * inbound untrusted-wrapper strip, the filter shape) and the untrusted marking of the answer by the
+ * TARGET resource's field stamps, the same list `autotask_read` of `<resource>.query` uses.
  */
 import { AutotaskConfigError } from 'node-autotask';
 import { stripUntrustedDeep } from 'node-autotask/untrusted';
-import { AGGREGATE_INPUT, assertFilterShape, closedInput } from './schemas.js';
+import { assertFilterShape } from './schemas.js';
 import { abortedAnswer } from './dispatch.js';
 import { markResult, ok } from './results.js';
 import { assertOperationPermitted } from '../policy.js';
+import { scopedCatalogCall } from './field-pointer.js';
 /** The server line for an SDK aggregate answer: numbers only, and the partial marker whenever the SDK flags truncation. */
 function summaryLine(operation, result) {
     const r = (result ?? {});
@@ -28,32 +29,35 @@ function summaryLine(operation, result) {
     const blindNote = r.blindSurface !== undefined && r.blindSurface !== false ? ' blindSurface: the surface could not be read, an empty result is not a true zero.' : '';
     return `${operation}: ${scanned}${groups}.${blindNote}${partial ? ' PARTIAL: the scan or the group list was cut short (hasMore / groupsTruncated); these are not tenant-wide totals, narrow the filter.' : ''}`;
 }
-/** `autotask_aggregate`: counts, totals and group-by sums over one `<resource>.query` surface. */
-export function buildAggregate(ctx) {
-    return {
-        title: 'Total, count or group-by sum over a query surface',
-        input: closedInput(AGGREGATE_INPUT),
-        run: async (raw, signal) => {
-            const args = raw;
-            const helper = 'operations.aggregate';
-            assertOperationPermitted(helper, ctx.record(helper), ctx.config, ctx.log);
-            const target = ctx.record(args.operation);
-            if (target === undefined) {
-                throw new AutotaskConfigError(`aggregate: unknown operation "${args.operation}": it is not in the capability registry (find the exact key with autotask_catalog)`, { operation: helper });
-            }
-            assertOperationPermitted(args.operation, target, ctx.config, ctx.log);
-            assertFilterShape(args.filter, helper);
-            const filter = stripUntrustedDeep(args.filter);
-            // The SDK's positional form: [operation, filter] and the opts bag only when a fold or cap was set.
-            const opts = {};
-            for (const key of ['groupBy', 'sum', 'top', 'limit'])
-                if (args[key] !== undefined)
-                    opts[key] = args[key];
-            const answer = await ctx.ops.invokeRead(ctx.client, helper, Object.keys(opts).length > 0 ? [args.operation, filter, opts] : [args.operation, filter], undefined, signal);
-            if (answer === undefined)
-                return abortedAnswer(ctx.correlationId);
-            return ok(summaryLine(args.operation, answer), { operation: args.operation, result: markResult(answer, ctx.untrustedFields(args.operation)) });
-        },
-    };
+/**
+ * Counts, totals and group-by sums over one `<resource>.query` surface: `autotask_query` with
+ * group_by / sum / count (#228). `extra` rides the data.
+ */
+export async function runAggregate(ctx, operation, rawFilter, opts, signal, extra = {}) {
+    const helper = 'operations.aggregate';
+    assertOperationPermitted(helper, ctx.record(helper), ctx.config, ctx.log);
+    const target = ctx.record(operation);
+    if (target === undefined) {
+        throw new AutotaskConfigError(`aggregate: unknown operation "${operation}": it is not in the capability registry (find the exact key with autotask_catalog)`, { operation: helper });
+    }
+    assertOperationPermitted(operation, target, ctx.config, ctx.log);
+    assertFilterShape(rawFilter, helper);
+    // the conditions array (a params bag's own filter when the caller sent the bag form)
+    const conditions = Array.isArray(rawFilter) ? rawFilter : (rawFilter.filter ?? []);
+    const filter = stripUntrustedDeep(conditions);
+    // The SDK's positional form: [operation, filter] and the opts bag only when a fold or cap was set.
+    const bag = {};
+    for (const key of ['groupBy', 'sum', 'top', 'limit', 'names'])
+        if (opts[key] !== undefined)
+            bag[key] = opts[key];
+    const answer = await ctx.ops.invokeRead(ctx.client, helper, Object.keys(bag).length > 0 ? [operation, filter, bag] : [operation, filter], undefined, signal).catch((err) => {
+        // node-autotask #280: a bad filter / groupBy / sum name is a zero-wire CONFIG_ERROR; point at the scoped field catalog
+        if (!(err instanceof AutotaskConfigError) || !err.message.includes('is not a field of'))
+            throw err;
+        throw new AutotaskConfigError(err.message, { operation: helper, suggestedAction: `Use exact vendor field names: ${scopedCatalogCall(operation.slice(0, operation.indexOf('.')))}.` });
+    });
+    if (answer === undefined)
+        return abortedAnswer(ctx.correlationId);
+    return ok(summaryLine(operation, answer), { ...extra, operation, result: markResult(answer, ctx.untrustedFields(operation)) });
 }
 //# sourceMappingURL=aggregate.js.map

package/dist/tools/capabilities-manifest.js

@@ -9,7 +9,6 @@ const CAPABILITY_IDS = {
     autotask_read: 'autotask.generic.read',
     autotask_resolve: 'autotask.discovery.resolve',
     autotask_query: 'autotask.discovery.query',
-    autotask_fetch_many: 'autotask.discovery.fetch_many',
     autotask_tenant_status: 'autotask.identity.tenant_status',
     autotask_ticket_full_context: 'autotask.ticket.full_context',
     autotask_company_full_profile: 'autotask.company.full_profile',

package/dist/tools/catalog-data.d.ts

@@ -19,6 +19,11 @@ export interface CatalogRow {
     reach: string | null;
     reachReason: string | null;
     boundedAlternative: string | null;
+    /** node-autotask 0.38.0 (#277): a repeated date-window helper, left out of default listings (still callable by key). */
+    hidden?: boolean;
+    hiddenReason?: string;
+    /** node-autotask 0.38.0: superseded (time_entries.recentTickets). */
+    deprecated?: boolean;
 }
 export interface MetaToolSpec {
     name: string;
@@ -56,6 +61,8 @@ export declare function recordById(operation: string): CapabilityRecord | undefi
  * name the deployment does not serve.
  */
 export declare const TOOL_NAME_BY_OP: Readonly<Record<string, string>>;
+/** The tool that serves one registry key: the table above, else `autotask_query` for any `<resource>.query` read (#228). */
+export declare function toolForOp(operation: string): string | undefined;
 /** The served tool for this row's operation in a deployment serving `served`, or `null`. */
 export declare function servedToolName(row: CatalogRow, served: ReadonlySet<string>): string | null;
 /** The registry keys projected onto an MCP tool name (the reverse of {@link TOOL_NAME_BY_OP}); empty when none. */
@@ -65,10 +72,10 @@ export declare const UNTRUSTED_NOTE = "Externally-sourced free text in the resul
 /** The record's plan-derived untrusted field list (the registry stamp). */
 export declare function untrustedFieldsOf(rec: CapabilityRecord): string[];
 /**
- * The resources that carry user-defined fields (#183 S8), derived from the registry with zero wire:
- * the plan's `udfCapable` entities (the ones whose SDK resource class normalises `userDefinedFields`)
- * are exactly the resources whose records stamp `UDF1` in `metadata.untrustedFields`. Not the
- * `getUdfInfo` set (every vendor entity has that metadata read, UDFs or not). A test pins the exact set.
+ * The resources that carry user-defined fields (#183 S8), read from the registry with zero wire:
+ * each record's published `udfCapable` flag (node-autotask 0.37.0 #254; the plan's entities whose SDK
+ * resource class normalises `userDefinedFields`). Not the `getUdfInfo` set (every vendor entity has
+ * that metadata read, UDFs or not). A test pins the exact set.
  */
 export declare const UDF_CAPABLE: ReadonlySet<string>;
 /** The per-tool description budget (A0 slimming: every served description <= 250 chars). */
@@ -109,7 +116,7 @@ export declare function cacheOptionsForPreset(preset: 'on' | 'off', fieldCacheTt
  * fails the boot (or the CI test) instead of quietly shipping a tool surface that no longer
  * describes the SDK behind it.
  */
-export declare const BUILT_AGAINST_PLAN_HASH = "08cf890fa1b2b50574638a1364993fced7e83a5dfd4f630763d80cdc01d5a5f1";
+export declare const BUILT_AGAINST_PLAN_HASH = "9bb87de7bcbda60f6c44955dba52b8e61e9c5547750ea8acacfcb6f261d7734f";
 /**
  * Fail fast when the installed SDK's plan has moved out from under this surface.
  * Called at boot (main.ts) and safe to call repeatedly (pure comparison).

package/dist/tools/catalog-data.js

@@ -4,7 +4,7 @@
  * Two sources, both shipped inside the `node-autotask` package:
  * - `MCP_TOOL_CATALOG.json` — the machine catalog: one row per registry operation (projected
  *   tool, effect, dry-run/confirm, required args, tier, reach) and the plan hash;
- * - the compiled capability registry (`node-autotask/capabilities`) — the 1,216-operation
+ * - the compiled capability registry (`node-autotask/capabilities`) — the 1,281-operation
  *   records the SDK's own invoke governor resolves against.
  *
  * The JSON file is NOT behind the package's `exports` map, so it is read from the installed
@@ -51,7 +51,6 @@ export const TOOL_NAME_BY_OP = {
     'threshold_information.get': 'autotask_tenant_status',
     'operations.resolveAny': 'autotask_resolve',
     'operations.searchAcrossResources': 'autotask_resolve',
-    'operations.fetchByIds': 'autotask_fetch_many',
     'operations.relationshipMap': 'autotask_describe',
     'companies.resolve': 'autotask_resolve',
     'companies.search': 'autotask_resolve',
@@ -67,7 +66,7 @@ export const TOOL_NAME_BY_OP = {
     'service_calls.query': 'autotask_query',
     'contracts.query': 'autotask_query',
     'time_off_requests.query': 'autotask_query',
-    'operations.aggregate': 'autotask_aggregate',
+    'operations.aggregate': 'autotask_query',
     'tickets.fullContext': 'autotask_ticket_full_context',
     'companies.fullProfile': 'autotask_company_full_profile',
     'projects.getContext': 'autotask_project_get_context',
@@ -82,9 +81,13 @@ export const TOOL_NAME_BY_OP = {
     'invoices.markupXml': 'autotask_invoice_get',
     'invoices.pdf': 'autotask_invoice_get',
 };
+/** The tool that serves one registry key: the table above, else `autotask_query` for any `<resource>.query` read (#228). */
+export function toolForOp(operation) {
+    return TOOL_NAME_BY_OP[operation] ?? (operation.endsWith('.query') && recordById(operation)?.effect === 'read' ? 'autotask_query' : undefined);
+}
 /** The served tool for this row's operation in a deployment serving `served`, or `null`. */
 export function servedToolName(row, served) {
-    const tool = TOOL_NAME_BY_OP[row.operation] ?? (row.effect === 'read' ? undefined : 'autotask_write');
+    const tool = toolForOp(row.operation) ?? (row.effect === 'read' ? undefined : 'autotask_write');
     return tool !== undefined && served.has(tool) ? tool : null;
 }
 /** The registry keys projected onto an MCP tool name (the reverse of {@link TOOL_NAME_BY_OP}); empty when none. */
@@ -102,12 +105,12 @@ export function untrustedFieldsOf(rec) {
     return Array.isArray(list) ? list : [];
 }
 /**
- * The resources that carry user-defined fields (#183 S8), derived from the registry with zero wire:
- * the plan's `udfCapable` entities (the ones whose SDK resource class normalises `userDefinedFields`)
- * are exactly the resources whose records stamp `UDF1` in `metadata.untrustedFields`. Not the
- * `getUdfInfo` set (every vendor entity has that metadata read, UDFs or not). A test pins the exact set.
+ * The resources that carry user-defined fields (#183 S8), read from the registry with zero wire:
+ * each record's published `udfCapable` flag (node-autotask 0.37.0 #254; the plan's entities whose SDK
+ * resource class normalises `userDefinedFields`). Not the `getUdfInfo` set (every vendor entity has
+ * that metadata read, UDFs or not). A test pins the exact set.
  */
-export const UDF_CAPABLE = new Set(RECORDS.filter((r) => untrustedFieldsOf(r).includes('UDF1')).map((r) => r.resource));
+export const UDF_CAPABLE = new Set(RECORDS.filter((r) => r.udfCapable).map((r) => r.resource));
 /** The per-tool description budget (A0 slimming: every served description <= 250 chars). */
 export const MAX_DESCRIPTION_CHARS = 250;
 /**
@@ -117,13 +120,11 @@ export const MAX_DESCRIPTION_CHARS = 250;
  */
 export const TOOL_DESCRIPTIONS = {
     autotask_guide: 'Step-by-step playbooks for multi-step Autotask tasks. No args: the index; {skill} returns one playbook, {skill, section} one section. Static text, no vendor call. Use it first when a task needs several tools.',
-    autotask_catalog: 'Find the exact operation key for anything without a dedicated tool: ranked search (q) over the 1,216 registry operations, with effect and whether this deployment serves it. No vendor call.',
+    autotask_catalog: 'Find the exact operation key for anything without a dedicated tool: ranked search (q) over the 1,281 registry operations, with effect and whether this deployment serves it. No vendor call.',
     autotask_describe: 'One operation\'s (registry key or tool name) exact input/output contract, examples, errors, policy verdict and playbooks (operation), or one resource\'s relationship map: parent, children, lookup keys (resource). No vendor call.',
-    autotask_read: 'Run reads by exact registry key, or up to 10 in one call: unbilled work, profitability and margin, SLA health. *.query: 50 rows; scope by company/contract ids (unscoped = tenant walk); roll-ups: autotask_aggregate; slim: includeFields, noteChars.',
-    autotask_resolve: 'Find the record behind an identifier: id or name, ticket number, CI serial, contact email (by), staff by email, user name or name (resource resources, include_api_users); one resource or a sweep. Exact by default; contains: companies, tickets, sweep.',
-    autotask_query: 'List records with a filter: tickets, time entries, service calls, contracts or time-off requests. Scope by company/contract ids (unscoped = tenant walk); roll-ups: autotask_aggregate. default 50, max 2500; latest N. Slim: include_fields, note_chars.',
-    autotask_aggregate: 'Totals, counts and group-by sums (hours by ticket) over any <resource>.query table without reading rows. No groupBy or sum = one count call. hasMore or groupsTruncated = a partial answer, never a tenant total.',
-    autotask_fetch_many: 'Fetch up to 500 records by numeric id across mixed resources in one call: items: [{resource, id, fields?}]. Answers data.results[{ok, operation, result|error}], ok, failed (same as autotask_read); a miss is a typed NOT_FOUND slot.',
+    autotask_read: 'Run reads by exact registry key, or up to 10 in one call: unbilled work, profitability and margin, SLA health. *.query: 50 rows; scope by company/contract ids (unscoped = tenant walk); totals: autotask_query group_by; slim: includeFields, noteChars.',
+    autotask_resolve: 'Find the record for an identifier: id or name, ticket number, CI serial, contact email (by), staff by email, user name or name (resource resources, include_api_users); one resource or a sweep. Exact, then contains on a miss.',
+    autotask_query: 'List records or totals with a filter: tickets, time entries, service calls, contracts, time off, more. Totals, no rows: group_by, sum, count (hours logged by ticket, how many match). By id: id in. Scope by company ids (unscoped = tenant walk).',
     autotask_tenant_status: 'Identity (API user + impersonated user), Autotask API version, this server\'s package/SDK version and profile (server), request thresholds, and the time zone of the people asking, with local and UTC time (time). Use it first to check credentials.',
     autotask_ticket_full_context: 'One ticket with its company, contact, assigned resource, project, notes, time entries and attachment metadata. Missing parts degrade to typed absent; a missing ticket is not found.',
     autotask_company_full_profile: 'One company with locations, contacts, notes, open tickets and projects, 10 rows per part (capped: true = more exist; raise the limit). fields {part:[names]} trims columns. Open = not tenant-closed. Missing parts degrade to typed absent.',
@@ -173,7 +174,7 @@ export function cacheOptionsForPreset(preset, fieldCacheTtlMs) {
  * fails the boot (or the CI test) instead of quietly shipping a tool surface that no longer
  * describes the SDK behind it.
  */
-export const BUILT_AGAINST_PLAN_HASH = '08cf890fa1b2b50574638a1364993fced7e83a5dfd4f630763d80cdc01d5a5f1';
+export const BUILT_AGAINST_PLAN_HASH = '9bb87de7bcbda60f6c44955dba52b8e61e9c5547750ea8acacfcb6f261d7734f';
 /**
  * Fail fast when the installed SDK's plan has moved out from under this surface.
  * Called at boot (main.ts) and safe to call repeatedly (pure comparison).

package/dist/tools/context/ops.js

@@ -1,7 +1,7 @@
 /** The default tool ops: the bounded query walk and the abort-signal wrapper (issue #91). */
 import { AutotaskClient, camelKey } from 'node-autotask';
 import { AutotaskConfigError } from 'node-autotask';
-import { fetchByIds, fetchMany, invokeDelete, invokeRead, invokeWrite, relationshipMap, resolveAny, searchAcrossResources } from 'node-autotask/operations';
+import { invokeDelete, invokeRead, invokeWrite, relationshipMap, resolveAny, searchAcrossResources } from 'node-autotask/operations';
 /** The real SDK bindings (the production default; tests substitute a fixture-backed bundle). */
 /**
  * The SDK operations bundle (the production default; tests substitute a fixture-backed bundle).
@@ -17,8 +17,6 @@ export const defaultToolOps = {
     invokeDelete: (client, operation, args, opts, signal) => withSignal(client, signal, () => invokeDelete(client, operation, args, opts ?? {})),
     resolveAny: (client, identifier, opts, signal) => withSignal(client, signal, () => resolveAny(client, identifier, opts ?? {})),
     searchAcrossResources: (client, query, opts, signal) => withSignal(client, signal, () => searchAcrossResources(client, query, opts ?? {})),
-    fetchMany: (client, items, opts, signal) => withSignal(client, signal, () => fetchMany(client, items, opts ?? {})),
-    fetchByIds: (client, items, opts, signal) => withSignal(client, signal, () => fetchByIds(client, items, opts ?? {})),
     relationshipMap: (client, resourceKey) => relationshipMap(client, resourceKey),
     hourlyBudget: (client) => Promise.resolve(client.hourlyBudget()),
     queryWalk: (client, operation, params, maxRows, signal) => withSignal(client, signal, () => walkQuery(client, operation, params, maxRows)),
@@ -45,6 +43,8 @@ export async function walkQuery(client, operation, params, maxRows) {
         bag.includeFields = params.includeFields;
     if (params.via !== undefined)
         bag.via = params.via;
+    if (params.names !== undefined)
+        bag.names = params.names;
     const items = [];
     for await (const item of holder.query(bag)) {
         if (items.length >= maxRows)