iit-mcp-autotask 0.35.1 → 0.36.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.37.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.37.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
@@ -21,7 +21,7 @@ client + SDK-owned TTL caches).
 
 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
+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.
 
@@ -763,7 +763,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.37.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 +773,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 +867,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

@@ -69,7 +69,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",
@@ -395,7 +395,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/tools/catalog-data.d.ts

@@ -65,10 +65,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 +109,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 = "5cd6c6679384651e7f67a0135915bcc031ef542640d9ebb6992b729ca42efe37";
 /**
  * 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
@@ -102,12 +102,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,7 +117,7 @@ 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.',
@@ -173,7 +173,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 = '5cd6c6679384651e7f67a0135915bcc031ef542640d9ebb6992b729ca42efe37';
 /**
  * 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/dispatch.d.ts

@@ -56,6 +56,13 @@ export declare function abortedAnswer(corr: string): ToolReturn;
  * in a 4xx body; the error wrap value-scrubs them before the envelope crosses.
  */
 export declare function requestSecrets(ctx: ToolContext): string[];
+/**
+ * A vendor TimeEntries continuation URL (#224; mirrors the SDK's cursorToPath + entryCursorPath, tighter):
+ * printable ASCII with no whitespace, absolute and already in canonical form, on this request's own Autotask origin, no userinfo, no
+ * fragment, exactly the continuation path, and only `paging` / `search` query parameters with encoded
+ * values. Anything else is not granted the cursor exemption (it is served as wrapped, capped vendor text).
+ */
+export declare function isEntryCursor(value: string, origin: string | undefined): boolean;
 /**
  * Per-operation post-processing for results read through `autotask_read`: the helper operations
  * that used to have their own tools carry vendor text beyond the registry stamp, and this is where

package/dist/tools/dispatch.js

@@ -15,8 +15,9 @@ import { AutotaskConfigError } from 'node-autotask';
 import { stripUntrustedDeep } from 'node-autotask/untrusted';
 import { assertFilterShape, QUERY_LIMIT, QUERY_RESOURCES } from './schemas.js';
 import { recordById, untrustedFieldsOf } from './catalog-data.js';
+import { AUTOTASK_BASE_PATH } from '../base-hosts.js';
 import { releaseClientOnError } from './context.js';
-import { abortedResult, closedArgsError, crossResourceUntrusted, errorContent, isFileOperation, markFilePayload, markResult, outcome, refusalContent } from './results.js';
+import { abortedResult, closedArgsError, crossResourceUntrusted, errorContent, isFileOperation, markFilePayload, markResult, markServerField, outcome, refusalContent } from './results.js';
 import { lastFullCalendarMonth, lastFullCalendarMonthLabel } from './profitability-window.js';
 import { assertOperationPermitted } from '../policy.js';
 import { ACK_KEY, guardUnscopedWalk, ScopeRequiredError } from './scope-guard.js';
@@ -143,6 +144,35 @@ export function requestSecrets(ctx) {
     }
     return out;
 }
+/** The time_entries posted-state reads whose `nextCursor` is a pass-back pagination cursor (SDK 0.37.0 #242). */
+const CURSOR_OPS = new Set(['time_entries.getPosted', 'time_entries.getUnposted', 'time_entries.postedWithin', 'time_entries.dateWorkedWindow']);
+/** The continuation path a TimeEntries cursor names, under the fixed base path (compared case-insensitively). */
+const ENTRY_CURSOR_PATH = `${AUTOTASK_BASE_PATH}/V1.0/TimeEntries/query/next`.toLowerCase();
+/** The query a vendor continuation URL carries: `paging` and `search`, URL-encoded values only. */
+const ENTRY_CURSOR_PARAM = /^(?:paging|search)=[A-Za-z0-9%._~+-]+$/;
+/**
+ * A vendor TimeEntries continuation URL (#224; mirrors the SDK's cursorToPath + entryCursorPath, tighter):
+ * printable ASCII with no whitespace, absolute and already in canonical form, on this request's own Autotask origin, no userinfo, no
+ * fragment, exactly the continuation path, and only `paging` / `search` query parameters with encoded
+ * values. Anything else is not granted the cursor exemption (it is served as wrapped, capped vendor text).
+ */
+export function isEntryCursor(value, origin) {
+    if (origin === undefined || !/^[\x21-\x7e]+$/.test(value) || !value.startsWith(`${origin}/`))
+        return false;
+    let u;
+    try {
+        u = new URL(value);
+    }
+    catch {
+        return false;
+    }
+    if (u.href !== value || u.origin !== origin || u.username !== '' || u.password !== '' || u.hash !== '' || value.includes('#'))
+        return false;
+    if (u.pathname.toLowerCase() !== ENTRY_CURSOR_PATH)
+        return false;
+    const query = u.search.replace(/^\?/, '');
+    return query === '' || query.split('&').every((p) => ENTRY_CURSOR_PARAM.test(p));
+}
 /** The reads behind the profitability result's customer and part containers (their untrusted stamps). */
 const PROFITABILITY_PART_OPS = [
     'contracts.profitability',
@@ -179,7 +209,30 @@ const PROFITABILITY_UNTRUSTED = [
  */
 export const READ_POSTPROCESS = {
     'contracts.profitability': (result) => markResult(result, PROFITABILITY_UNTRUSTED),
+    'operations.revenueRollup': markRevenueRollup,
 };
+/**
+ * `operations.revenueRollup` (SDK 0.37.0): the helper rows carry no `metadata.untrustedFields`. Vendor text
+ * sits in `rows[].keys.<dimension>` (`name`, `division`, `label`) and in the values of
+ * `coverage.contractTypeMap` / `contractCategoryMap` (id -> picklist label). The cross-resource list
+ * covers `name` and `label` at every depth; `division` (the LOB level-1 name) is added. ponytail: the
+ * `coverage.excluded.otherContract*` maps are keyed by label, and a key cannot be wrapped (it is still
+ * cleaned and capped by the output sanitiser).
+ */
+const ROLLUP_UNTRUSTED = [...crossResourceUntrusted(), 'division'];
+function markRevenueRollup(result) {
+    const out = markResult(result, ROLLUP_UNTRUSTED);
+    const cov = out?.coverage;
+    for (const key of ['contractTypeMap', 'contractCategoryMap']) {
+        const map = cov?.[key];
+        if (map === null || typeof map !== 'object' || Array.isArray(map))
+            continue;
+        for (const [id, label] of Object.entries(map))
+            if (typeof label === 'string')
+                markServerField(map, id, 'wrap');
+    }
+    return out;
+}
 /**
  * Server-built annotations added to a served result AFTER the untrusted marking (issue #102). Each
  * `operations.fieldCatalog` resource row says which `autotask_query` operation serves it (or null:
@@ -295,6 +348,10 @@ export async function readOneItem(ctx, operation, args, signal, opts) {
     }
     const nameChecked = operation.endsWith('.query') || operation.endsWith('.count');
     const result = await ctx.ops.invokeRead(ctx.client, operation, cleanArgs, opts, signal).catch((err) => {
+        // #224: a refused cursor the caller passed is the caller's input; a refused vendor continuation is not
+        if (CURSOR_OPS.has(operation) && err?.code === 'RESPONSE_REJECTED' && cleanArgs.some((a) => a !== null && typeof a === 'object' && typeof a.cursor === 'string')) {
+            Object.assign(err, { callerInput: true });
+        }
         throw nameChecked ? rewriteFieldNameRefusal(err, operation, operation.slice(0, operation.lastIndexOf('.')), 'read') : err;
     });
     if (result === undefined)
@@ -312,6 +369,11 @@ export async function readOneItem(ctx, operation, args, signal, opts) {
     const projected = result !== null && typeof result === 'object' ? markResult(result, crossResourceUntrusted()) : result;
     if (isFileOperation(operation))
         markFilePayload(projected);
+    // #224: the posted-state reads' nextCursor goes back verbatim as opts.cursor; the 500 cap would cut it
+    const cursor = CURSOR_OPS.has(operation) && projected !== null && typeof projected === 'object' ? projected.nextCursor : undefined;
+    // only a TimeEntries continuation URL is a cursor; anything else is vendor text (500 cap, wrapped)
+    if (typeof cursor === 'string')
+        markServerField(projected, 'nextCursor', isEntryCursor(cursor, ctx.origin) ? 'cursor' : 'wrap');
     if (operation === 'operations.fieldCatalog')
         annotateCatalogRows(projected);
     return { result: projected, ...(note !== undefined ? { note } : {}), ...(scopeNote !== undefined ? { scopeNote } : {}) };

package/dist/tools/meta.js

@@ -18,6 +18,7 @@
 import { AutotaskConfigError } from 'node-autotask';
 import { effectiveRequiredFields } from 'node-autotask/operations';
 import { UDF_MERGE_NOTE, UDF_NONE, UDF_ROWS_NOTE, associationFields, associationRules, caveatNotes, constraintNotes, coupledNotes, dateConventionNotes, statusScopeNote, udfDefinitionRows, udfMergeNote, udfMoreNote, udfUnavailable } from './write-guidance.js';
+import { scrubDeep, scrubProvenance } from './provenance-scrub.js';
 import { CATALOG, RECORDS, SDK_VERSION, TOOL_NAME_BY_OP, UDF_CAPABLE, opsForTool, recordById, servedToolName, untrustedFieldsOf } from './catalog-data.js';
 import { releaseClientOnError } from './context.js';
 import { abortedAnswer, InputInvalidError, readOneItem, requestSecrets } from './dispatch.js';
@@ -259,7 +260,7 @@ const NO_CREATE_NOTE = 'do not look for a create operation: this server has none
 /**
  * S8 (#183): the UDF block for `describe {resource}`: the mechanism facts (SDK row shape) + the definitions
  * pointer. Zero wire: the capability fact is the registry itself (UDF_CAPABLE: the resources whose records
- * stamp UDF1, the plan's udfCapable entities; SDK 0.34.0 #219 N7), and the definitions are the live tenant
+ * carry the published udfCapable flag, SDK 0.37.0 #254; SDK 0.34.0 #219 N7), and the definitions are the live tenant
  * read the pointer names (the scoped fieldCatalog read with the `udf` include).
  */
 function udfBlock(resource) {
@@ -316,7 +317,7 @@ async function guidanceFor(ctx, rec, reachable) {
         // #173: the positional [from, to, opts] mixes types; the same window as one uniform-string filter
         return {
             exampleArgs: ['2026-10-20', '2026-10-22', { resourceID: 123 }],
-            sameWindowAsQuery: 'autotask_query {resource:"time_entries", filter:[{field:"resourceID",op:"eq",value:"123"},{field:"dateWorked",op:"gte",value:"2026-10-20"},{field:"dateWorked",op:"lte",value:"2026-10-22"}], limit:500}: the same rows up to limit (the window caps at 500; dateWorked is a date, both days inclusive), without the posted counts, for a client that cannot send a mixed-type array.',
+            sameWindowAsQuery: 'autotask_query {resource:"time_entries", filter:[{field:"resourceID",op:"eq",value:"123"},{field:"dateWorked",op:"gte",value:"2026-10-20"},{field:"dateWorked",op:"lte",value:"2026-10-22"}], limit:500}: the same rows up to limit (one window call returns at most 500 and a nextCursor to pass as cursor for the rest; dateWorked is a date, both days inclusive), without the posted counts, for a client that cannot send a mixed-type array.',
         };
     }
     if (op === 'moveToTicket') {
@@ -352,8 +353,9 @@ async function guidanceFor(ctx, rec, reachable) {
             // The SDK's one precedence (live-proven > zone > spec) is a create fact; an update keeps the vendor's own set.
             const zone = op === 'create' ? await zoneFactsOf(ctx, rec.resource) : undefined;
             facts = zone?.createGuidance ?? undefined;
-            // the SDK's quirks are free text (provenance, tenant names, operator advice): none of it is served on a create, only a pointer
-            hasQuirks = (zone?.quirks?.length ?? 0) > 0;
+            // quirk statements are SDK free text: none is served on a create, only a pointer, and only when a quirk
+            // names the create op (SDK 0.37.0 #253 structured quirks; #224)
+            hasQuirks = (zone?.quirks ?? []).some((q) => Array.isArray(q?.ops) && q.ops.includes('create'));
             const eff = op === 'create' ? effectiveRequiredFields({ requiredFields: spec }, zone) : { fields: spec, from: 'spec', unproven: true };
             // eff.fields is already the unconditional set (value-gated fields are in eff.conditional, SDK 0.34.0)
             required = eff.fields;
@@ -416,21 +418,32 @@ async function zoneFactsOf(ctx, resource) {
 }
 /** The one read envelope of autotask_read and autotask_fetch_many (#97), served on the on-demand surface. */
 const READ_ENVELOPE = 'data = { results: Slot[], ok: <count>, failed: <count>, budget?, budgetWarning? }, always an array in input order, one slot for a single read. Slot = { ok: true, operation, result, windowNote?, scopeNote? } or { ok: false, operation, error }; autotask_fetch_many slots also echo resource and id (operation is "<resource>.get"; a miss is { ok: false, error: { code: "NOT_FOUND" } }). A single read that fails still answers the whole-call error envelope.';
-/** Served relationship map: createGuidance without the SDK's free text (`vendorEvidence`, `blocker.message`/`remedy`). */
+/** Served relationship map without the SDK's free text: createGuidance loses `vendorEvidence` and
+ * `blocker.message`/`remedy`; each structured `zoneFacts.quirks` entry loses `evidence` (SDK 0.37.0 #253: raw
+ * campaign strings) in {@link scrubDeep}, which drops every string `evidence` key and scrubs the rest (#224). */
 function projectMap(map) {
     const m = map;
-    const g = m?.zoneFacts?.createGuidance;
-    if (g === undefined || g === null || typeof g !== 'object')
-        return map;
-    const slim = { ...g };
-    delete slim.vendorEvidence;
-    if (slim.blocker !== null && typeof slim.blocker === 'object') {
-        const b = { ...slim.blocker };
-        delete b.message;
-        delete b.remedy;
-        slim.blocker = b;
+    const z = m?.zoneFacts;
+    if (z === undefined || z === null || typeof z !== 'object')
+        return scrubDeep(map);
+    const zone = { ...z };
+    // #224: a live write keeps its op and outcome; its date and note are maintainer history
+    const lw = z.liveWrites;
+    if (Array.isArray(lw))
+        zone.liveWrites = lw.map((w) => (w !== null && typeof w === 'object' ? { op: w.op, outcome: w.outcome } : w));
+    const g = z.createGuidance;
+    if (g !== undefined && g !== null && typeof g === 'object') {
+        const slim = { ...g };
+        delete slim.vendorEvidence;
+        if (slim.blocker !== null && typeof slim.blocker === 'object') {
+            const b = { ...slim.blocker };
+            delete b.message;
+            delete b.remedy;
+            slim.blocker = b;
+        }
+        zone.createGuidance = slim;
     }
-    return { ...m, zoneFacts: { ...m.zoneFacts, createGuidance: slim } };
+    return scrubDeep({ ...m, zoneFacts: zone });
 }
 /** Served record: `metadata.caveats` rows keep kind/fields/remedyOp, not the SDK's free-text `note`. */
 function projectCaveats(rec) {
@@ -460,14 +473,15 @@ function servedUsage(rec) {
     // the read-back is one `<resource>.get`: a create with no get in the registry answers `data.record: null`
     return u.includes(CREATE_USAGE_FALSE) && recordById(`${rec.resource}.get`) !== undefined ? u.replace(CREATE_USAGE_FALSE, CREATE_USAGE_TRUE) : u;
 }
-/** Served record: caveats projected and the create usage corrected (AC24). */
+/** Served record: caveats projected, the create usage corrected (AC24), the SDK's own test list dropped and
+ * its maintainer provenance scrubbed (#224). */
 function servedRecord(rec) {
-    const projected = projectCaveats(rec);
+    const projected = { ...projectCaveats(rec) };
+    delete projected.tests;
     const md = projected.metadata;
-    const usage = servedUsage(projected);
-    if (typeof md?.usage !== 'string' || usage === undefined || md.usage === usage)
-        return projected;
-    return { ...projected, metadata: { ...md, usage } };
+    const usage = servedUsage(rec);
+    const out = typeof md?.usage !== 'string' || usage === undefined || md.usage === usage ? projected : { ...projected, metadata: { ...md, usage } };
+    return scrubDeep(out);
 }
 /** The per-field caps of a describe summary (characters): purpose, args and usage only, about 2 KB in all (#197). */
 const SUMMARY_CAPS = { purpose: 500, args: 600, usage: 400 };
@@ -486,13 +500,13 @@ function summariseRecord(ctx, operation, viaTool) {
     const reason = refusalReason(operation, rec, ctx.config, ctx.writable);
     const md = (rec.metadata ?? {});
     const row = CATALOG.catalog.find((r) => r.operation === operation);
-    const text = (v) => (typeof v === 'string' ? v : '');
+    const text = (v) => (typeof v === 'string' ? scrubProvenance(v) : '');
     const cut = [];
     const tool = viaTool ?? TOOL_NAME_BY_OP[operation];
     return ok(`Summary of "${rec.id}" (purpose, args, usage).`, {
         operation: rec.id,
         ...(tool !== undefined ? { tool, ...toolServed(ctx, tool) } : {}),
-        purpose: capText(text(md.purpose) || (row?.purpose ?? ''), SUMMARY_CAPS.purpose, 'purpose', cut),
+        purpose: capText(text(md.purpose) || text(row?.purpose), SUMMARY_CAPS.purpose, 'purpose', cut),
         requiredArgs: row?.requiredArgs ?? [],
         args: capText(text(md.args), SUMMARY_CAPS.args, 'args', cut),
         usage: capText(text(servedUsage(rec)), SUMMARY_CAPS.usage, 'usage', cut),

package/dist/tools/provenance-scrub.d.ts

@@ -0,0 +1,20 @@
+/**
+ * tools/provenance-scrub.ts — maintainer provenance out of the SDK text `autotask_describe` serves (#224).
+ *
+ * The SDK's registry records and relationship maps carry its own build history inside otherwise useful
+ * guidance: the test zone (`ww29`), verification dates, issue numbers, campaign stages and markers, wall
+ * ids. None of it helps a model call the API, and some of it is tenant-identifying. Only the provenance
+ * tokens are removed: a parenthetical is split into clauses (`;`, ` — `, `, ` at its own depth) and only a
+ * clause that itself carries a marker is edited; a bare date survives unless its clause carries a marker
+ * (a format example such as `e.g. 2026-01-01` stays); a parenthetical left empty is dropped.
+ * Deterministic text surgery, not a guarantee: a marker the patterns below do not name passes through.
+ * ponytail: pattern list, extend it when an SDK bump adds a new marker shape.
+ */
+/** Object nesting bound for {@link scrubDeep}; deeper subtrees are dropped, never served unscrubbed. */
+export declare const MAX_DEEP = 32;
+export declare const MAX_PAREN_DEPTH = 16;
+/** `text` with the provenance tokens removed (a text with no marker is returned as it is). */
+export declare function scrubProvenance(text: string): string;
+export declare function scrubExample(text: string): string;
+/** A deep copy with every string scrubbed (`examples` by {@link scrubExample}) and the provenance-only string keys dropped. */
+export declare function scrubDeep(value: unknown, depth?: number): unknown;

package/dist/tools/provenance-scrub.js

@@ -0,0 +1,209 @@
+/**
+ * tools/provenance-scrub.ts — maintainer provenance out of the SDK text `autotask_describe` serves (#224).
+ *
+ * The SDK's registry records and relationship maps carry its own build history inside otherwise useful
+ * guidance: the test zone (`ww29`), verification dates, issue numbers, campaign stages and markers, wall
+ * ids. None of it helps a model call the API, and some of it is tenant-identifying. Only the provenance
+ * tokens are removed: a parenthetical is split into clauses (`;`, ` — `, `, ` at its own depth) and only a
+ * clause that itself carries a marker is edited; a bare date survives unless its clause carries a marker
+ * (a format example such as `e.g. 2026-01-01` stays); a parenthetical left empty is dropped.
+ * Deterministic text surgery, not a guarantee: a marker the patterns below do not name passes through.
+ * ponytail: pattern list, extend it when an SDK bump adds a new marker shape.
+ */
+const DATE = String.raw `20\d\d-\d\d-\d\d`;
+/** A provenance marker (a clause carrying one is edited; the others are left as they are). */
+const MARKER = new RegExp(String.raw `ww29|\bAU03\b|australia-nz|live-verified|\bissues? #\d+|\bPR #\d+|^#\d+(?:,\s*#\d+)*$|\bstage[- ]\d+\b|FULL100W-\d+|\bconfirm-\d+\b|\bre-(?:walled|stamped|verified|probed)\b|\bW-[A-Z]\d+\b|\b(?:measured|live|verified|re-verified|fetched|on)\s+${DATE}`, 'i');
+/** Token removals, in order; `inner` ones apply only inside a marker clause of a parenthetical. */
+const TOKENS = [
+    [/^\s*issues? #\d+(?:,\s*#\d+)*\s*:\s*/i, '', 'any'],
+    [/\bissues? #\d+(?:,\s*#\d+)*/gi, '', 'any'],
+    [/\bPR #\d+/g, '', 'any'],
+    [/^\s*#\d+(?:,\s*#\d+)*\s*$/, '', 'inner'],
+    [/\b(?:the )?W-[A-Z]\d+ (?:wall|pointer note)\b|\bwall W-[A-Z]\d+\b|\bW-[A-Z]\d+:?/g, '', 'any'],
+    [/\b(?:the )?stage[- ]\d+(?: apply[- ]matrix)?\b/gi, '', 'any'],
+    [/\b(?:marker )?FULL100W-\d+|\bconfirm-\d+\b/g, '', 'any'],
+    [/\blive-verified\b/gi, 'verified', 'any'],
+    [new RegExp(String.raw `\bmeasured\s+${DATE}(?::[^;,)]*)?|\b(?:live|verified|re-verified|fetched|on)\s+${DATE}:?`, 'gi'), '', 'any'],
+    [/\bww29[- ](?:proven|zone-labelled)\b/g, 'zone-proven', 'any'],
+    [/\bin ww29\b/g, 'in this zone', 'outer'],
+    [/\bww29\b/g, 'this zone', 'outer'],
+    [/\bww29\b/g, 'this zone', 'inner'],
+    [/\baustralia-nz\b|\bAU03\b/g, '', 'any'],
+    [new RegExp(String.raw `\b${DATE}\b`, 'g'), '', 'inner'],
+];
+function tokens(text, where) {
+    let out = text;
+    for (const [rx, to, scope] of TOKENS)
+        if (scope === 'any' || scope === where)
+            out = out.replace(rx, to);
+    return out;
+}
+/** Collapse the gaps a removal leaves: doubled spaces, a space before punctuation, doubled separators. */
+function tidy(text) {
+    return text
+        .replace(/(?<=\S)[ \t]{2,}/g, ' ')
+        .replace(/ +([,;:)]|\.(?!\.))/g, '$1')
+        .replace(/\( +/g, '(')
+        .replace(/([,;:])(?:\s*[,;:])+/g, '$1')
+        .replace(/[,;:]\)/g, ')')
+        .replace(/\s*[—–]\s*\)/g, ')');
+}
+/** What a marker clause can reduce to that carries no fact of its own. */
+const EMPTY_CLAUSE = /^(?:(?:live|verified|re-verified|re-walled|re-stamped|re-probed|scope|on|in|this|zone|the)\s*)+$/i;
+const DATE_ONLY = new RegExp(String.raw `^\s*${DATE}\s*$`);
+/** Separators and spaces left at either end of an edited clause. */
+const LEFTOVER = /^[\s,;:—–-]+|[\s,;:—–-]+$/g;
+/** Split at `;`, ` — ` and `, ` at depth 0 (kept as separators), edit marker clauses only, drop emptied ones. */
+function clauses(inner) {
+    const parts = [];
+    let depth = 0;
+    let start = 0;
+    for (let i = 0; i < inner.length; i++) {
+        const c = inner[i];
+        if (c === '(')
+            depth++;
+        else if (c === ')')
+            depth--;
+        else if (depth === 0) {
+            const sep = c === ';' ? 1 : inner.startsWith(' — ', i) ? 3 : inner.startsWith(', ', i) ? 2 : 0;
+            if (sep > 0) {
+                parts.push(inner.slice(start, i), inner.slice(i, i + sep));
+                start = i + sep;
+                i += sep - 1;
+            }
+        }
+    }
+    parts.push(inner.slice(start));
+    // even indexes are clauses, odd ones the separator before the next clause
+    const kept = [];
+    // a clause that is only a date is provenance when a sibling clause carries a marker ("wall W-A7, stage 11, <date>")
+    const sibling = parts.some((p, k) => k % 2 === 0 && MARKER.test(p.trim()));
+    for (let k = 0; k < parts.length; k += 2) {
+        const clause = parts[k];
+        const marked = MARKER.test(clause.trim()) || (sibling && DATE_ONLY.test(clause));
+        const edited = marked ? tidy(tokens(clause, 'inner')).replace(LEFTOVER, '').replace(EMPTY_CLAUSE, '') : clause;
+        if (sibling && clause.trim() === '')
+            continue;
+        if (!marked || edited.trim() !== '')
+            kept.push({ text: marked && k > 0 && /^\s/.test(clause) ? ` ${edited}` : edited, sep: k > 0 ? parts[k - 1] : '' });
+    }
+    return kept.map((p, n) => (n === 0 ? p.text.replace(/^\s+/, '') : p.sep + p.text)).join('');
+}
+const MAX_DEPTH = 16;
+/** Object nesting bound for {@link scrubDeep}; deeper subtrees are dropped, never served unscrubbed. */
+export const MAX_DEEP = 32;
+export const MAX_PAREN_DEPTH = MAX_DEPTH;
+/** Scrub a segment: parentheticals recursively (innermost first), then this level's text. */
+function segment(text, inParen, depth = 0) {
+    // ponytail: nesting past this depth is left as it is (no fact is dropped; a deep marker may pass)
+    if (depth > MAX_DEPTH)
+        return text;
+    let out = '';
+    let i = 0;
+    while (i < text.length) {
+        const open = text.indexOf('(', i);
+        if (open === -1) {
+            out += text.slice(i);
+            break;
+        }
+        let level = 0;
+        let close = -1;
+        for (let j = open; j < text.length; j++) {
+            if (text[j] === '(')
+                level++;
+            else if (text[j] === ')' && --level === 0) {
+                close = j;
+                break;
+            }
+        }
+        if (close === -1) {
+            out += text.slice(i);
+            break;
+        }
+        out += text.slice(i, open);
+        const raw = text.slice(open + 1, close);
+        const inner = clauses(segment(raw, true, depth + 1));
+        if (inner.trim() === '' && raw.trim() !== '')
+            out = out.replace(/[ \t]+$/, '');
+        else
+            out += `(${inner})`;
+        i = close + 1;
+    }
+    return inParen ? out : tidy(tokens(out, 'outer')).replace(/^[\s,;:—–-]+/, '');
+}
+const ANY_MARKER = new RegExp(`${MARKER.source}|\\(#\\d+`, 'i');
+/**
+ * Rewrites applied to the whole text before the clause pass: campaign labels and issue tags that sit in
+ * running prose, and the zone name where dropping it reads better than "this zone".
+ */
+const PRE = [
+    [/^\s*W-?[A-Z]?\d+(?=\s*[(:])\s*:?\s*/, ''],
+    [/\bww29\/australia-nz:?\s*/g, ''],
+    [/\bww29[- ]zone-labelled\b|\bzone-labelled ww29\b/g, 'zone-labelled'],
+    [/\b(the|a) ww29 /g, '$1 '],
+    [/\bpre- or post-#\d+/g, 'before or after that change'],
+    [/\bpre-#\d+/g, 'earlier'],
+    [/\bpost-#\d+/g, 'later'],
+    [/\bdiscrepancy #\d+/g, 'a documented discrepancy'],
+    [/\bthe issue-#\d+ /g, 'the '],
+    [/(?<![Tt]icket |[Nn]o\.? |[Nn]umber |[Ii]ssues? )#\d{2,4} (?=[a-z_])/g, ''],
+    [/\s*[—-]\s*residue records under ticket \d+(?:, name=marker)?/g, ''],
+    [/\b(?:the )?S\d+[a-z]?(?:-[A-Z])? live(?: wire)? oracle:?\s*/g, ''],
+    [/\bS\d+-[A-Z] live run:\s*/g, ''],
+    [/\bS\d+-[A-Z] [A-Z] probes\b/g, 'probes'],
+    [/\bthe S\d+[a-z]?(?:-[A-Z])? scratch (ticket|record)\b/g, 'a sample $1'],
+    [/\bthe S\d+-[A-Z] (typed )?sentinel\b/g, 'the $1sentinel'],
+    [/,?\s*\bS\d+-[A-Z] [A-Z]\d+(?:\/[A-Z]\d+)*(?=[)\s,;])/g, ''],
+    [/\b\d\d-\d\d text\b/g, 'vendor text'],
+    [/\b(\w+'s) \d\d-\d\d wall\b/g, '$1 wall'],
+];
+/** `text` with the provenance tokens removed (a text with no marker is returned as it is). */
+export function scrubProvenance(text) {
+    let out = text;
+    for (const [rx, to] of PRE)
+        out = out.replace(rx, to);
+    return ANY_MARKER.test(out) ? segment(out, false) : out === text ? text : tidy(out);
+}
+/**
+ * The SDK's `examples` are code samples and prose notes. Their argument values are kept (sample ids and
+ * dates are what a call looks like), but the campaign tokens are not: a record name such as `WW29-S11A-C2`
+ * reads `Example`, a run label (`S11-A C2`, `the S12-B run`) and a bare `#N` issue tag are removed, a
+ * campaign email and first name read `jane.doe@example.com` / `Jane`, then the text gets the same scrub as any other served string.
+ */
+const EXAMPLE_TOKENS = [
+    [/\bWW29-S\d+[A-Z]?-[A-Z]\d+\b/g, 'Example'],
+    [/\b(?:the )?S\d+[a-z]?(?:-[A-Z])? run\b/g, 'a run'],
+    [/[\w.+-]+@ww29[\w.-]*/g, 'jane.doe@example.com'],
+    [/\bfirstName: 'Max'/g, "firstName: 'Jane'"],
+    [/\bS\d+-[A-Z] [A-Z]\d+ /g, ''],
+    [/\blive-validated\b/g, 'validated'],
+    [/(?<=\s)#\d{2,4} (?=[a-z_])/g, ''],
+];
+export function scrubExample(text) {
+    let out = text;
+    for (const [rx, to] of EXAMPLE_TOKENS)
+        out = out.replace(rx, to);
+    return scrubProvenance(out);
+}
+/** String-valued keys that are provenance only, dropped at any depth: the zone label and the raw evidence strings. */
+const DROP_STRING_KEYS = new Set(['zone', 'evidence', 'vendorEvidence']);
+/** A deep copy with every string scrubbed (`examples` by {@link scrubExample}) and the provenance-only string keys dropped. */
+export function scrubDeep(value, depth = 0) {
+    if (typeof value === 'string')
+        return scrubProvenance(value);
+    if (value === null || typeof value !== 'object')
+        return value;
+    // ponytail: fail closed past the depth bound (a subtree this deep would pass unscrubbed); the registry sweep test pins that none is
+    if (depth > MAX_DEEP)
+        return undefined;
+    if (Array.isArray(value))
+        return value.map((v) => scrubDeep(v, depth + 1));
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+        if (DROP_STRING_KEYS.has(k) && (typeof v === 'string' || Array.isArray(v)))
+            continue;
+        out[k] = k === 'examples' && Array.isArray(v) ? v.map((e) => (typeof e === 'string' ? scrubExample(e) : scrubDeep(e, depth + 1))) : scrubDeep(v, depth + 1);
+    }
+    return out;
+}
+//# sourceMappingURL=provenance-scrub.js.map

package/dist/tools/reasons.d.ts

@@ -11,7 +11,7 @@ export declare const STATUSES: readonly ["ok", "needs_input", "ambiguous", "deni
 export type Status = (typeof STATUSES)[number];
 export declare const NEXT_ACTIONS: readonly ["proceed", "supply_input", "choose_candidate", "repreview", "manual_action", "poll_task", "verify_then_repreview", "retry", "stop"];
 export type NextAction = (typeof NEXT_ACTIONS)[number];
-export declare const REASON_CODES: readonly ["INPUT_INVALID", "TARGET_NOT_FOUND", "AMBIGUOUS_MATCH", "RESULT_TRUNCATED", "POLICY_DENIED", "HOST_POLICY_DENIED", "CREDENTIAL_MISSING", "CREDENTIAL_MALFORMED", "UNAUTHORIZED", "RATE_LIMITED", "ABORTED", "UPSTREAM_ERROR", "INTERNAL_ERROR", "INPUT_MISSING", "SCOPE_REQUIRED", "OP_NOT_ALLOWED", "TARGET_NOT_IN_SCOPE", "MOVE_UNRESOLVED", "MOVE_REFUSED", "LIMIT_RATE", "DUPLICATE_EXISTS", "COOLDOWN_ACTIVE", "KILL_SWITCH", "STATE_UNAVAILABLE", "GATE_UNSUPPORTED", "GATE_DECLINED", "PLAN_NOT_FOUND", "PLAN_EXPIRED", "PRINCIPAL_MISMATCH", "STATE_DRIFT", "IDEMPOTENCY_CONFLICT", "WRITE_FAILED", "FIELD_NOT_PERSISTED", "WRITE_OUTCOME_UNKNOWN"];
+export declare const REASON_CODES: readonly ["INPUT_INVALID", "TARGET_NOT_FOUND", "AMBIGUOUS_MATCH", "RESULT_TRUNCATED", "POLICY_DENIED", "HOST_POLICY_DENIED", "CREDENTIAL_MISSING", "CREDENTIAL_MALFORMED", "UNAUTHORIZED", "RATE_LIMITED", "ABORTED", "UPSTREAM_ERROR", "INTERNAL_ERROR", "BUDGET_EXCEEDED", "INPUT_MISSING", "SCOPE_REQUIRED", "OP_NOT_ALLOWED", "TARGET_NOT_IN_SCOPE", "MOVE_UNRESOLVED", "MOVE_REFUSED", "LIMIT_RATE", "DUPLICATE_EXISTS", "COOLDOWN_ACTIVE", "KILL_SWITCH", "STATE_UNAVAILABLE", "GATE_UNSUPPORTED", "GATE_DECLINED", "PLAN_NOT_FOUND", "PLAN_EXPIRED", "PRINCIPAL_MISMATCH", "STATE_DRIFT", "IDEMPOTENCY_CONFLICT", "WRITE_FAILED", "FIELD_NOT_PERSISTED", "WRITE_OUTCOME_UNKNOWN"];
 export type ReasonCode = (typeof REASON_CODES)[number];
 export interface Reason {
     code: ReasonCode;
@@ -27,6 +27,7 @@ export declare function classifyError(payload: {
     category?: unknown;
     retryable?: unknown;
     httpStatus?: unknown;
+    callerInput?: unknown;
 }): {
     status: Status;
     next: NextAction;

package/dist/tools/reasons.js

@@ -33,6 +33,7 @@ export const REASON_CODES = [
     'ABORTED',
     'UPSTREAM_ERROR',
     'INTERNAL_ERROR',
+    'BUDGET_EXCEEDED',
     // the operator write path (autotask_write / autotask_apply)
     'INPUT_MISSING',
     'SCOPE_REQUIRED',
@@ -85,6 +86,15 @@ export function classifyError(payload) {
     if (INPUT_CODES.has(code) || payload.category === 'validation') {
         return { status: 'error', next: 'supply_input', code: 'INPUT_INVALID', retryable: false };
     }
+    // SDK 0.37.0: a budgeted helper (operations.revenueRollup, the time_entries countOnly walk) refused before or
+    // during the walk; the same input fails again, a narrower window or scope, or a raised maxVendorCalls, may not
+    if (code === 'BUDGET_EXCEEDED')
+        return { status: 'error', next: 'supply_input', code: 'BUDGET_EXCEEDED', retryable: false };
+    // the SDK refused a pagination cursor the CALLER passed (a time_entries posted-state cursor that was edited,
+    // cut, or carried to another window; dispatch marks callerInput): pass nextCursor back unchanged, or omit it.
+    // A refused vendor continuation (generic query paging) is not the caller's input and falls through below.
+    if (code === 'RESPONSE_REJECTED' && payload.callerInput === true)
+        return { status: 'error', next: 'supply_input', code: 'INPUT_INVALID', retryable: false };
     if (RATE_CODES.has(code))
         return { status: 'error', next: 'retry', code: 'RATE_LIMITED', retryable: true };
     if (code === 'ABORTED')

package/dist/tools/results/errors.js

@@ -304,6 +304,8 @@ export function typedErrorPayload(err, correlationId, secrets = []) {
         payload.retryAfter = retryAfter;
     if (e.notSent === true)
         payload.notSent = true;
+    if (e.callerInput === true)
+        payload.callerInput = true;
     // V23/FT-5: the vendor body crosses bounded + scrubbed, never raw (a string body serves its
     // shape; an object body keeps structure with scrubbed/capped strings, dropped to a shape
     // descriptor past the total cap).

package/dist/tools/results/untrusted.d.ts

@@ -28,7 +28,7 @@ export declare function stripUnsafeChars(text: string): string;
  * Clean one untrusted value: strip the unsafe characters, then (when `cap`) cut at
  * {@link UNTRUSTED_TEXT_CAP}; a cut value carries {@link TRUNCATION_MARKER}.
  */
-export declare function cleanUntrustedText(text: string, cap?: boolean): string;
+export declare function cleanUntrustedText(text: string, cap?: boolean, max?: number): string;
 /** One character outside the base64 alphabet (a linear test: no backtracking, any length). */
 export declare const NOT_BASE64: RegExp;
 /** Nesting past this depth is dropped rather than walked (final review R7). */
@@ -42,16 +42,21 @@ export declare const EVERY_ITEM = "*";
  * - `server`: a value the server built from values that already passed the choke point (a TSV
  *   table): kept as it is;
  * - `binary`: the file payload of a download (sanitiser review S1/S2): kept uncapped only while it
- *   is pure base64, otherwise it is vendor text like any other. No other field is ever exempt
- *   from the cap, whatever its content looks like.
+ *   is pure base64, otherwise it is vendor text like any other;
+ * - `cursor`: a pagination cursor the caller passes back verbatim (the `nextCursor` of the four
+ *   time_entries posted-state reads, #224): cleaned and unwrapped, capped at {@link CURSOR_CAP} (the
+ *   SDK refuses a longer one) instead of 500, a cut one carrying the truncation marker.
+ * No other field is ever exempt from the cap, whatever its content looks like.
  * Keyed by the exact object the server built (a WeakMap: vendor data can never be in it), so a
  * vendor key that merely shares a name (`tsv`, `result`) at any depth is plain vendor text.
  */
-export type Provenance = 'wrap' | 'document' | 'server' | 'binary';
+export type Provenance = 'wrap' | 'document' | 'server' | 'binary' | 'cursor';
+/** The cap on a `cursor` value: the SDK's own cursor cap (a longer cursor is refused before any request). */
+export declare const CURSOR_CAP = 2048;
 export declare const PROVENANCE: WeakMap<object, Map<string, Provenance>>;
 export declare function note(target: object, key: string, kind: Provenance): void;
 /** Record that `target[key]` is a server-built document or table (see {@link Provenance}). */
-export declare function markServerField(target: object, key: string, kind: 'document' | 'server' | 'binary' | 'wrap'): void;
+export declare function markServerField(target: object, key: string, kind: Provenance): void;
 export interface SanitiseOptions {
     /** false: no cap anywhere (the output_path file form). */
     cap?: boolean;

package/dist/tools/results/untrusted.js

@@ -33,11 +33,11 @@ export function stripUnsafeChars(text) {
  * Clean one untrusted value: strip the unsafe characters, then (when `cap`) cut at
  * {@link UNTRUSTED_TEXT_CAP}; a cut value carries {@link TRUNCATION_MARKER}.
  */
-export function cleanUntrustedText(text, cap = true) {
+export function cleanUntrustedText(text, cap = true, max = UNTRUSTED_TEXT_CAP) {
     const clean = stripUnsafeChars(text);
-    if (!cap || clean.length <= UNTRUSTED_TEXT_CAP)
+    if (!cap || clean.length <= max)
         return clean;
-    let cut = clean.slice(0, UNTRUSTED_TEXT_CAP);
+    let cut = clean.slice(0, max);
     // never end on half a surrogate pair (final review R8)
     if (/[\uD800-\uDBFF]$/.test(cut))
         cut = cut.slice(0, -1);
@@ -49,6 +49,8 @@ export const NOT_BASE64 = /[^A-Za-z0-9+/=\r\n]/;
 export const MAX_OUTPUT_DEPTH = 64;
 /** The per-array provenance key: applies to every string item of an array. */
 export const EVERY_ITEM = '*';
+/** The cap on a `cursor` value: the SDK's own cursor cap (a longer cursor is refused before any request). */
+export const CURSOR_CAP = 2048;
 export const PROVENANCE = new WeakMap();
 export function note(target, key, kind) {
     let fields = PROVENANCE.get(target);
@@ -119,6 +121,8 @@ export function sanitiseVendorOutput(value, opts = {}, kind, depth = 0) {
         const text = inner ?? value;
         if (kind === 'document')
             return wrapOrSelf(cleanUntrustedText(text, false));
+        if (kind === 'cursor' && inner === undefined)
+            return cleanUntrustedText(text, cap, CURSOR_CAP);
         const clean = cleanUntrustedText(text, cap);
         return kind === 'wrap' || inner !== undefined ? wrapOrSelf(clean) : clean;
     }

package/dist/tools/schemas.d.ts

@@ -144,6 +144,7 @@ export declare const ENVELOPE: z.ZodObject<{
             ABORTED: "ABORTED";
             UPSTREAM_ERROR: "UPSTREAM_ERROR";
             INTERNAL_ERROR: "INTERNAL_ERROR";
+            BUDGET_EXCEEDED: "BUDGET_EXCEEDED";
             INPUT_MISSING: "INPUT_MISSING";
             SCOPE_REQUIRED: "SCOPE_REQUIRED";
             OP_NOT_ALLOWED: "OP_NOT_ALLOWED";

package/dist/tools/server-version.d.ts

@@ -1,3 +1,3 @@
 /** The wire identity of this server: a leaf module (no imports) so any tool can read it without an import cycle. */
 export declare const SERVER_NAME = "iit-mcp-autotask";
-export declare const SERVER_VERSION = "0.35.1";
+export declare const SERVER_VERSION = "0.36.0";

package/dist/tools/server-version.js

@@ -1,4 +1,4 @@
 /** The wire identity of this server: a leaf module (no imports) so any tool can read it without an import cycle. */
 export const SERVER_NAME = 'iit-mcp-autotask';
-export const SERVER_VERSION = '0.35.1';
+export const SERVER_VERSION = '0.36.0';
 //# sourceMappingURL=server-version.js.map

package/dist/tools/server.d.ts

@@ -60,7 +60,7 @@ export declare function serverInstructions(config: Pick<Config, 'AUTOTASK_PROFIL
 /** The full identity stamp (the `/metadata` build block — the era pair, FR-2). */
 export declare const SERVER_IDENTITY: {
     readonly name: "iit-mcp-autotask";
-    readonly version: "0.35.1";
+    readonly version: "0.36.0";
     readonly mcpProtocolBaseline: "2026-07-28";
     readonly legacyProtocolFallback: "2025-11-25";
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iit-mcp-autotask",
-  "version": "0.35.1",
+  "version": "0.36.0",
   "description": "MCP server for the Autotask (Datto) PSA domain, built on the node-autotask SDK",
   "license": "MIT",
   "author": "Max Soukhomlinov",
@@ -53,7 +53,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/server": "^2.2.0",
-    "node-autotask": "0.34.0",
+    "node-autotask": "0.37.0",
     "zod": "^4.6.7"
   },
   "devDependencies": {

package/server.json

@@ -1,6 +1,6 @@
 {
   "name": "iit-mcp-autotask",
-  "version": "0.35.1",
+  "version": "0.36.0",
   "description": "MCP server for the Autotask (Datto) PSA API, powered by the node-autotask SDK",
   "mcpProtocolBaseline": "2026-07-28",
   "legacyProtocolFallback": "2025-11-25",
@@ -61,7 +61,7 @@
   "capabilitiesManifest": "capabilities.json",
   "sdk": {
     "package": "node-autotask",
-    "versionRange": "0.34.0"
+    "versionRange": "0.37.0"
   },
   "vendorExtensions": false,
   "credentialModelNote": "per-request; server-held under stdio or, on HTTP, only behind AUTOTASK_HTTP_AUTH=tokens; operator plans and the ledger are keyed by principal and tenant id, never by credential, and an apply uses the credential on the apply request"

package/skills/filter-semantics.md

@@ -28,7 +28,7 @@ No inputs: this is a reference page about the filter behaviour of autotask_query
 3. tickets.search is a vendor contains on the TITLE only: no free-text search, no matched-field reporting, and vendor contains is looser than a literal substring (case/token matching can return MORE hits than a local title-substring check). The per-field contains of tickets.query is the precise tool.
 4. Unassigned FKs are not uniform. tickets store 0; time_entries store NULL. Unallocated time needs notExist (ticketID eq 0 finds nothing); assignedResourceID eq 0 and notExist differ.
 5. Field names are vendor casing, and an unknown field name now fails pre-dispatch as a typed CONFIG_ERROR with the field-catalog pointer, with zero query wire (0.20.0 pre-validation), on all five autotask_query operations (tickets.query, time_entries.query, service_calls.query, contracts.query, time_off_requests.query). One udf: true condition per query is exempt from the name check. List names for the queried resource with the scoped call `autotask_read {operation:"operations.fieldCatalog", args:[{resources:["<resource>"]}]}` (add `fields: [names]` to project, `labels: true`; never `<resource>.getFieldInfo`). Never the bare `operations.fieldCatalog`: it serves the whole five-resource catalog (~85 KB) and has no row for time_entries, service_calls, contracts or time_off_requests. Do not guess names. The answer is `data.results[0].result`.
-6. Some clients (Copilot Studio) fail locally, before any request, when one array mixes value types (a number beside a string in one filter, or dateWorkedWindow args: strings plus an object). The autotask_query filter declares value as a string, so write every value as a string ("<resource id>", "2026-10-22", "true"); numbers still work for clients that send them. For a time entry window over a resource or ticket, query time entries instead of dateWorkedWindow: `autotask_query {resource:"time_entries", filter:[{field:"resourceID",op:"eq",value:"<resource id>"},{field:"dateWorked",op:"gte",value:"2026-10-20"},{field:"dateWorked",op:"lte",value:"2026-10-22"}], limit:500}`: the window's rows up to limit (dateWorkedWindow caps at 500; the query defaults to 50), both days inclusive because dateWorked is a date, without the posted counts (derive them from postedDate where the zone serves it). A bare window with no narrowing is `autotask_read {operation:"time_entries.dateWorkedWindow", args:["2026-10-20","2026-10-22"]}` (all strings). The server and SDK pass filter values through unchanged; string dates, ids and booleans are confirmed on resources and time_entries, other fields are not verified.
+6. Some clients (Copilot Studio) fail locally, before any request, when one array mixes value types (a number beside a string in one filter, or dateWorkedWindow args: strings plus an object). The autotask_query filter declares value as a string, so write every value as a string ("<resource id>", "2026-10-22", "true"); numbers still work for clients that send them. For a time entry window over a resource or ticket, query time entries instead of dateWorkedWindow: `autotask_query {resource:"time_entries", filter:[{field:"resourceID",op:"eq",value:"<resource id>"},{field:"dateWorked",op:"gte",value:"2026-10-20"},{field:"dateWorked",op:"lte",value:"2026-10-22"}], limit:500}`: the window's rows up to limit (dateWorkedWindow returns 500 per call plus a nextCursor to pass back as cursor; the query defaults to 50), both days inclusive because dateWorked is a date, without the posted counts. A bare window with no narrowing is `autotask_read {operation:"time_entries.dateWorkedWindow", args:["2026-10-20","2026-10-22"]}` (all strings). The server and SDK pass filter values through unchanged; string dates, ids and booleans are confirmed on resources and time_entries, other fields are not verified.
 7. tickets.assignedResourceID is the PRIMARY owner only. Secondary assignments live in the separate ticket_secondary_resources table, which carries no status, so "how many open tickets does <resource> have" cannot be answered from tickets.query alone or from that table alone. Use `autotask_resource_workload {id}`: its open_tickets part is the de-duplicated union of primary and secondary open tickets with counts {primary, secondary, both, open} for the returned rows, plus exact totals {primary, secondary, both, open, capped} from a separate count read. For "how many" quote totals, not counts. totals.capped true means the SDK's link-read cap was hit (the totals are a lower bound); it is not the row value.capped, which only says the returned rows were cut at ticket_limit. If totalsAbsent is set the count read failed (it is the error code): the rows are still valid, and counts describe only them. When value.capped is true the rows are partial: call again with a larger ticket_limit (up to 500) before listing them, and say so if it is still capped. If the part is absent with CLOSED_STATUS_UNRESOLVED the tenant's closed statuses could not be read: say the count is unavailable rather than guessing.
 8. Scope every `*.query` by ids (`eq`/`in` on `*ID`): unscoped is a tenant-wide walk, refused above 500 rows unless `acknowledge_unscoped` (query) or `acknowledgeUnscoped` (read). Totals/sums: `autotask_aggregate`.