iit-mcp-autotask 0.38.2 → 0.38.4

package/README.md

@@ -9,9 +9,9 @@ packaged playbooks, strong security boundaries, and predictable per-tenant in-pr
 client + SDK-owned TTL caches).
 
 > **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
+> at `0.39.1`; 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.38.0`) — never a `file:`, `git:`, `link:` or workspace reference
+> (node-autotask pinned exactly at `0.39.1`) — 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
@@ -47,7 +47,9 @@ examples; `full: true` serves the complete record, `summary: true` about 2 KB),
   `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"}]`
+  `groupsTruncated` mean partial). `filter` is not schema-required (a form-filler dead-ends on a
+  required Table, #241) but a missing or empty one is refused (`INPUT_INVALID`, rows and totals);
+  `{field: "id", op: "exist"}` targets the whole entity. 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
@@ -778,7 +780,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.38.0`** (an exact pin —
+`iit-mcp-autotask` depends on **`node-autotask` from npm at exactly `0.39.1`** (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

package/dist/tools/dispatch.d.ts

@@ -22,20 +22,6 @@ export declare class InputInvalidError extends AutotaskConfigError {
     readonly field?: string;
     constructor(message: string, field?: string, operation?: string);
 }
-/**
- * A typed read-path answer for a WELL-FORMED but incomplete input (issue #56: one of the two
- * profitability window dates without the other). Unlike the thrown SDK/config errors (which the
- * frame maps to the `error` envelope), this one answers the NON-error `needs_input` envelope
- * (`next: supply_input`) — the read path's needs_input, the same shape the write path answers for
- * its missing inputs. In the `items` form of `autotask_read` it rides the per-item slot as a typed
- * payload (code `INPUT_MISSING`), like any other slot error.
- */
-export declare class NeedsInputError extends Error {
-    readonly code: "INPUT_MISSING";
-    readonly field: string;
-    readonly missing: readonly string[];
-    constructor(message: string, field: string, missing: readonly string[]);
-}
 /**
  * The shared call frame, run by EVERY registered handler:
  * 1. the closed top-level argument set (issue #3: an unknown key is refused with the typed
@@ -93,7 +79,7 @@ export interface ReadOutcome {
  * One registry read, through every gate in order: the unknown-operation refusal, the deployment
  * policy (reads only; credential-minting never), the ONE-level `<untrusted_content>` strip of the
  * inputs, the query/count filter-shape gate, the `contracts.profitability` window default (issue
- * #56: both dates absent → the last full calendar month, UTC; exactly one → needs_input), the
+ * #56: both dates absent → the last full calendar month, UTC; exactly one → INPUT_INVALID), the
  * governed invoke (the SDK's single read governor) and the untrusted projection of the result.
  * Errors are THROWN — the frame wraps them once, the `items` form maps them per slot.
  */

package/dist/tools/dispatch.js

@@ -17,10 +17,10 @@ import { assertFilterShape, normalizeFilter, ownField, QUERY_LIMIT } from './sch
 import { recordById, toolForOp, 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, markServerField, outcome, refusalContent } from './results.js';
+import { abortedResult, closedArgsError, crossResourceUntrusted, errorContent, isFileOperation, markFilePayload, markResult, markServerField, 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';
+import { ACK_KEY, guardUnscopedWalk } from './scope-guard.js';
 import { rewriteFieldNameRefusal } from './field-pointer.js';
 /** The MCP request's AbortSignal, when the transport provides one (architecture 7.6). */
 function mcpSignal(extra) {
@@ -36,24 +36,6 @@ export class InputInvalidError extends AutotaskConfigError {
             this.field = field;
     }
 }
-/**
- * A typed read-path answer for a WELL-FORMED but incomplete input (issue #56: one of the two
- * profitability window dates without the other). Unlike the thrown SDK/config errors (which the
- * frame maps to the `error` envelope), this one answers the NON-error `needs_input` envelope
- * (`next: supply_input`) — the read path's needs_input, the same shape the write path answers for
- * its missing inputs. In the `items` form of `autotask_read` it rides the per-item slot as a typed
- * payload (code `INPUT_MISSING`), like any other slot error.
- */
-export class NeedsInputError extends Error {
-    code = 'INPUT_MISSING';
-    field;
-    missing;
-    constructor(message, field, missing) {
-        super(message);
-        this.field = field;
-        this.missing = missing;
-    }
-}
 /**
  * The shared call frame, run by EVERY registered handler:
  * 1. the closed top-level argument set (issue #3: an unknown key is refused with the typed
@@ -93,16 +75,6 @@ async function frame(ctx, input, rawArgs, extra, work) {
     }
     catch (err) {
         releaseClientOnError(ctx, err);
-        // The read path's needs_input (issue #56): a well-formed but incomplete input answers the
-        // NON-error needs_input envelope (next: supply_input) — never the error mapping.
-        if (err instanceof NeedsInputError) {
-            return outcome('needs_input', 'supply_input', { code: 'INPUT_MISSING', field: err.field, detail: err.message }, null, { missing: [...err.missing] });
-        }
-        // The unscoped-walk refusal (#197): a well-formed read that needs a scope filter answers the
-        // NON-error needs_input envelope (reason SCOPE_REQUIRED), like the half profitability window.
-        if (err instanceof ScopeRequiredError) {
-            return outcome('needs_input', 'supply_input', { code: 'SCOPE_REQUIRED', field: 'filter', detail: `${err.message} ${err.suggestedAction}` }, { code: err.code, operation: err.operation, count: err.count, threshold: err.threshold, suggestedAction: err.suggestedAction }, { missing: ['/args/0/filter'] });
-        }
         // V23/FT-5: the request's own credential values ride into the error wrap so a vendor body
         // that echoes them is value-scrubbed before it crosses.
         return errorContent(err, ctx.correlationId, requestSecrets(ctx));
@@ -268,7 +240,7 @@ function annotateCatalogRows(result) {
  * One registry read, through every gate in order: the unknown-operation refusal, the deployment
  * policy (reads only; credential-minting never), the ONE-level `<untrusted_content>` strip of the
  * inputs, the query/count filter-shape gate, the `contracts.profitability` window default (issue
- * #56: both dates absent → the last full calendar month, UTC; exactly one → needs_input), the
+ * #56: both dates absent → the last full calendar month, UTC; exactly one → INPUT_INVALID), the
  * governed invoke (the SDK's single read governor) and the untrusted projection of the result.
  * Errors are THROWN — the frame wraps them once, the `items` form maps them per slot.
  */
@@ -284,6 +256,8 @@ export async function readOneItem(ctx, operation, args, signal, opts) {
     // pre-request (zero wire on a refused shape).
     if (operation.endsWith('.query') || operation.endsWith('.count')) {
         // No params bag at all (args omitted / []): the same bounded default (#83); the SDK's own bag-less form is unbounded.
+        // #243: a missing or [] filter stays accepted here (limit 50; the walk guard above 500 rows): autotask_read is the generic
+        // path and this bounded default is its contract; autotask_query refuses the missing filter because it is the guided surface.
         if (operation.endsWith('.query') && cleanArgs[0] === undefined)
             cleanArgs[0] = { limit: QUERY_LIMIT.parse(undefined) };
         const given = cleanArgs[0];
@@ -316,9 +290,20 @@ export async function readOneItem(ctx, operation, args, signal, opts) {
             cleanArgs[0] = bag;
         }
     }
+    // #238: operations.aggregate [operation, filter, {groupBy, sum}] gets the own-field alias like the *.query bag and autotask_query
+    if (operation === 'operations.aggregate' && typeof cleanArgs[0] === 'string') {
+        const resource = cleanArgs[0].slice(0, cleanArgs[0].lastIndexOf('.'));
+        if (cleanArgs[1] !== undefined)
+            cleanArgs[1] = normalizeFilter(cleanArgs[1], resource);
+        const b = cleanArgs[2];
+        if (b !== null && typeof b === 'object' && !Array.isArray(b)) {
+            const own = (v) => (Array.isArray(v) ? v.map((n) => (typeof n === 'string' ? ownField(resource, n) : n)) : v);
+            cleanArgs[2] = { ...b, ...('groupBy' in b ? { groupBy: own(b.groupBy) } : {}), ...('sum' in b ? { sum: own(b.sum) } : {}) };
+        }
+    }
     // #56: the contracts.profitability window default. NO opts bag (or a bag with neither date): the
     // last full calendar month (UTC) fills BOTH days, and the outcome carries the transparency note.
-    // EXACTLY ONE date: needs_input — a half window is never sent (the caller supplies both or
+    // EXACTLY ONE date: INPUT_INVALID — a half window is never sent (the caller supplies both or
     // neither). BOTH dates: the caller's window passes through (the SDK validates format, order and
     // the 36-month cap). The fill rides the closed opts bag BEFORE the SDK's validation — it adds
     // the two dates and never renames a key. A null/array/scalar second arg is not an opts bag: the
@@ -347,7 +332,9 @@ export async function readOneItem(ctx, operation, args, signal, opts) {
             const hasFrom = typeof bag.dateFrom === 'string' && bag.dateFrom.length > 0;
             const hasTo = typeof bag.dateTo === 'string' && bag.dateTo.length > 0;
             if (hasFrom !== hasTo) {
-                throw new NeedsInputError('contracts.profitability: pass both dateFrom and dateTo, or neither — one day without the other is not a window (with neither, the window defaults to the last full calendar month, UTC)', hasFrom ? 'args[1].dateTo' : 'args[1].dateFrom', ['/args/1/dateFrom', '/args/1/dateTo']);
+                // #243: a recoverable INPUT_INVALID error (next supply_input), not needs_input: rule 3 reads that as "stop".
+                // Within the 200-char message bound (MAX_ERROR_MESSAGE_CHARS): a longer one is cut mid-sentence.
+                throw new InputInvalidError(`contracts.profitability: pass both dateFrom and dateTo, or neither. Call again with ${hasFrom ? 'dateTo' : 'dateFrom'} set too, or drop ${hasFrom ? 'dateFrom' : 'dateTo'} (with neither, the window is the last full calendar month, UTC).`, hasFrom ? 'args[1].dateTo' : 'args[1].dateFrom');
             }
             if (!hasFrom && !hasTo) {
                 const now = new Date();

package/dist/tools/lists.js

@@ -51,6 +51,13 @@ export function buildQuery(ctx) {
             if (rec === undefined || rec.effect !== 'read') {
                 throw new InputInvalidError(`query: "${args.resource}" has no ${operation} read in the registry (find the resource with autotask_catalog)`, 'resource');
             }
+            // #241: filter is optional in the advertised schema (a form-filler dead-ends on a required Table), so a missing or
+            // empty one is refused here, rows and totals alike (unscoped totals answer the wrong scope), before any wire. An
+            // INPUT_INVALID error, as when the schema required it: a model retries it; needs_input reads as "stop" (rule 3). autotask_read *.query keeps its bounded no-filter default (limit 50; #83, #243).
+            if (args.filter === undefined || (Array.isArray(args.filter) && args.filter.length === 0)) {
+                // within the 200-char message bound (MAX_ERROR_MESSAGE_CHARS): a longer one is cut mid-word
+                throw new InputInvalidError('query: filter is missing or empty; call again with a scope such as {field: "companyID", op: "eq", value: "<id>"} (time_entries: ticket.companyID), or {field: "id", op: "exist"} for the whole entity', 'filter');
+            }
             // #228: totals mode (group_by / sum / count) is the SDK's operations.aggregate over the same filter
             if (args.group_by !== undefined || args.sum !== undefined || args.count === true) {
                 const clash = ['latest', 'include_fields', 'note_chars', 'via', 'format', 'output_path', 'acknowledge_unscoped', 'untrusted_wrapper'].find((k) => args[k] !== undefined);

package/dist/tools/meta.js

@@ -251,7 +251,7 @@ function toolServed(ctx, tool) {
 /** Defaults this server applies before the SDK sees the call (dispatch.ts readOneItem); the registry record does not know them. */
 const SERVER_DEFAULTS = {
     'operations.fieldCatalog': `via autotask_read: compact rows unless fields is non-empty (then full rows, labels true) or labels is true (full rows), maxBytes ${FIELD_CATALOG_MAX_BYTES} (truncated + truncation when cut); any value you pass wins`,
-    'contracts.profitability': 'via autotask_read, dateFrom and dateTo are optional: with neither (or no opts bag) the window defaults to the last full calendar month (UTC) and the result carries a windowNote; exactly one date is refused (needs_input)',
+    'contracts.profitability': 'via autotask_read, dateFrom and dateTo are optional: with neither (or no opts bag) the window defaults to the last full calendar month (UTC) and the result carries a windowNote; exactly one date is refused (INPUT_INVALID: pass both or neither)',
 };
 /** AC27 (#183): a vendor entity with no create in the registry (live case: invoices) says so on its reads, mirroring
  * the served no-DELETE `deleteBoundary` data; a "raise an invoice" question gets answered, not hunted. Zero wire.

package/dist/tools/reasons.js

@@ -86,6 +86,9 @@ export function classifyError(payload) {
     if (INPUT_CODES.has(code) || payload.category === 'validation') {
         return { status: 'error', next: 'supply_input', code: 'INPUT_INVALID', retryable: false };
     }
+    // #243: the unscoped-walk refusal (scope-guard.ts) is a recoverable error: add the scope (or acknowledge) and call again
+    if (code === 'SCOPE_REQUIRED')
+        return { status: 'error', next: 'supply_input', code: 'SCOPE_REQUIRED', 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')

package/dist/tools/resolves.js

@@ -425,7 +425,7 @@ export function buildResolve(ctx) {
                 if (found === undefined)
                     return abortedAnswer(ctx.correlationId);
                 const rows = found.map((t) => (a.expand ? { resource, ref: refOf('tickets', t), record: slimRecord(t, a.expand) } : ticketRow(t)));
-                const miss = rows.length === 0 ? ' No title contains that text: the work may use other words; find it by activity: autotask_query {resource: "time_entries", filter: [resourceID eq, dateWorked gte], group_by: ["ticketID"], sum: ["hoursWorked"]}.' : '';
+                const miss = rows.length === 0 ? ' No title contains that text: the work may use other words; find it by activity: autotask_query {resource: "time_entries", filter: [resourceID eq, dateWorked gte], group_by: ["ticketID"], sum: ["hoursWorked", "hoursToBill"]}.' : '';
                 return ok(`Ticket title search "${a.identifier}"${a.company_id !== undefined ? ` (company ${a.company_id})` : ''}: ${rows.length} match(es).${miss}`, {
                     resource,
                     match: 'contains',

package/dist/tools/schemas.d.ts

@@ -40,16 +40,17 @@ export declare const COMPANY_PROFILE_PART_LIMIT_DEFAULT = 10;
  * and/or groups are accepted unchanged). Only field/op/value are advertised: a form-filling client
  * fills every property it is shown, and a filled `udf` or `items` would change the query.
  * #231: the advertised condition is explicit for strict form-fillers (one prepared a required Table
- * with no rows and sent nothing): all three keys required, `op` the 13-operator enum, and an
- * `examples` entry (a relation filter plus a UTC date bound). exist/notExist take value "", which
- * {@link normalizeFilter} drops before dispatch.
+ * with no rows and sent nothing): `op` the 13-operator enum and an `examples` entry (a relation
+ * filter plus a UTC date bound). exist/notExist take value "", which {@link normalizeFilter} drops
+ * before dispatch. #241: `filter` and a condition's `value` are not required (Copilot Studio left the
+ * required Table unfilled and asked the user); the query handler refuses a missing or empty filter.
  */
 export declare const FILTER_OPS: readonly ["eq", "noteq", "gt", "gte", "lt", "lte", "beginsWith", "endsWith", "contains", "exist", "notExist", "in", "notIn"];
 /** #234: a `<self>.<field>` name on its own resource without the prefix; any other name unchanged. */
 export declare function ownField(resource: string, name: string): string;
 /**
  * #231: drop the empty `value` a strict form-filler sends on exist/notExist (the advertised schema
- * requires one on every condition). #234: a `<self>.<field>` condition on `resource` names the own
+ * required one on every condition until #241). #234: a `<self>.<field>` condition on `resource` names the own
  * field ({@link ownField}). Everything else passes through unchanged, groups and the bag form included.
  */
 export declare function normalizeFilter(filter: unknown, resource?: string): unknown;
@@ -60,9 +61,9 @@ export declare function normalizeFilter(filter: unknown, resource?: string): unk
  * the typed CONFIG_ERROR BEFORE any request is built (zero wire). node-autotask before 0.9.0
  * silently DROPPED a bare object's conditions, so an unrefused bare object queried UNFILTERED;
  * 0.9.0 refuses it too (#83), and this server's refusal stays the zero-wire pre-request
- * guarantee. The `filter` key itself is required by `QUERY_INPUT` — a no-filter call is refused at the
- * dispatch frame before this validator runs (the served `latest` description states this); the
- * `undefined` early return remains for direct callers of the validator.
+ * guarantee. The `filter` key is optional in `QUERY_INPUT` (#241): the query handler refuses a
+ * missing or empty one (INPUT_INVALID) before this validator runs; the `undefined` early return
+ * serves autotask_read, whose `<resource>.query` params bag may omit it.
  */
 export declare function assertFilterShape(filter: unknown, operation: string): void;
 /** A registered input: the StandardSchema the SDK sees, the zod object the frame parses, the key set. */
@@ -289,7 +290,7 @@ export declare const RESOLVE_INPUT: z.ZodObject<{
 }, z.core.$strip>;
 export declare const QUERY_INPUT: z.ZodObject<{
     resource: z.ZodString;
-    filter: z.ZodUnknown;
+    filter: z.ZodOptional<z.ZodUnknown>;
     limit: z.ZodOptional<z.ZodNumber>;
     group_by: z.ZodOptional<z.ZodArray<z.ZodString>>;
     sum: z.ZodOptional<z.ZodArray<z.ZodString>>;

package/dist/tools/schemas.js

@@ -72,21 +72,23 @@ const COMPANY_PROFILE_PART_LIMIT_LOCATIONS = z
  * and/or groups are accepted unchanged). Only field/op/value are advertised: a form-filling client
  * fills every property it is shown, and a filled `udf` or `items` would change the query.
  * #231: the advertised condition is explicit for strict form-fillers (one prepared a required Table
- * with no rows and sent nothing): all three keys required, `op` the 13-operator enum, and an
- * `examples` entry (a relation filter plus a UTC date bound). exist/notExist take value "", which
- * {@link normalizeFilter} drops before dispatch.
+ * with no rows and sent nothing): `op` the 13-operator enum and an `examples` entry (a relation
+ * filter plus a UTC date bound). exist/notExist take value "", which {@link normalizeFilter} drops
+ * before dispatch. #241: `filter` and a condition's `value` are not required (Copilot Studio left the
+ * required Table unfilled and asked the user); the query handler refuses a missing or empty filter.
  */
 export const FILTER_OPS = ['eq', 'noteq', 'gt', 'gte', 'lt', 'lte', 'beginsWith', 'endsWith', 'contains', 'exist', 'notExist', 'in', 'notIn'];
 const FILTER = z
     .unknown()
+    .optional()
     .meta({
     type: 'array',
     // op keeps type string beside the enum: a Table client types each column from `type` (#173)
-    items: { type: 'object', properties: { field: { type: 'string' }, op: { type: 'string', enum: FILTER_OPS }, value: { type: 'string' } }, required: ['field', 'op', 'value'] },
+    items: { type: 'object', properties: { field: { type: 'string' }, op: { type: 'string', enum: FILTER_OPS }, value: { type: 'string' } }, required: ['field', 'op'] },
     // one filter copied verbatim by form-fillers: the ticket relation on time_entries, the own fields on tickets (#234)
     examples: [[{ field: 'ticket.companyID', op: 'eq', value: '123' }, { field: 'ticket.createDate', op: 'gte', value: '2026-10-01T00:00:00Z' }]],
 })
-    .describe('Conditions; write every value as a string ("29", "true"; exist/notExist: ""; in/notIn: "1,2,3"). Dates: UTC ISO-8601. An unknown field name (also group_by, sum) is a pre-query CONFIG_ERROR. ticket.<field> scopes time entries by their ticket; on tickets use the plain field.');
+    .describe('Needed (missing or [] is refused). Conditions; write every value as a string ("29", "true"; exist/notExist: ""; in/notIn: "1,2,3"). Dates: UTC ISO-8601. An unknown field name (also group_by, sum) is a pre-query CONFIG_ERROR. ticket.<field> scopes time entries by their ticket; on tickets use the plain field.');
 /**
  * #234: the SDK's relation targets. On the target resource itself `<self>.` can only mean an own
  * field (none of them carries a `<self>ID`), so `ticket.companyID` on tickets is `companyID`; the SDK
@@ -100,7 +102,7 @@ export function ownField(resource, name) {
 }
 /**
  * #231: drop the empty `value` a strict form-filler sends on exist/notExist (the advertised schema
- * requires one on every condition). #234: a `<self>.<field>` condition on `resource` names the own
+ * required one on every condition until #241). #234: a `<self>.<field>` condition on `resource` names the own
  * field ({@link ownField}). Everything else passes through unchanged, groups and the bag form included.
  */
 export function normalizeFilter(filter, resource = '') {
@@ -131,9 +133,9 @@ export function normalizeFilter(filter, resource = '') {
  * the typed CONFIG_ERROR BEFORE any request is built (zero wire). node-autotask before 0.9.0
  * silently DROPPED a bare object's conditions, so an unrefused bare object queried UNFILTERED;
  * 0.9.0 refuses it too (#83), and this server's refusal stays the zero-wire pre-request
- * guarantee. The `filter` key itself is required by `QUERY_INPUT` — a no-filter call is refused at the
- * dispatch frame before this validator runs (the served `latest` description states this); the
- * `undefined` early return remains for direct callers of the validator.
+ * guarantee. The `filter` key is optional in `QUERY_INPUT` (#241): the query handler refuses a
+ * missing or empty one (INPUT_INVALID) before this validator runs; the `undefined` early return
+ * serves autotask_read, whose `<resource>.query` params bag may omit it.
  */
 export function assertFilterShape(filter, operation) {
     if (filter === undefined)
@@ -307,7 +309,7 @@ export const QUERY_INPUT = z.object({
     count: z.boolean().optional().describe('true: count the matching rows, no rows returned.'),
     top: z.number().int().min(1).max(100).optional().describe('Groups kept, 1-100 (default 25).'),
     include_fields: z.array(z.string().min(1)).optional().describe('Exact vendor field names to return (id always included); an unknown name is a pre-query CONFIG_ERROR. Absent: tickets and time_entries return default columns, others the full row.'),
-    latest: z.number().int().min(1).max(2500).optional().describe('N newest records (highest id). filter is required on this tool (a no-filter call is refused); to target the whole entity pass the tautology {field: id, op: exist}. Needs limit >= N (limit defaults to 50).'),
+    latest: z.number().int().min(1).max(2500).optional().describe('N newest records (highest id). A filter is needed on this tool (a no-filter call is refused); to target the whole entity pass the tautology {field: id, op: exist}. Needs limit >= N (limit defaults to 50).'),
     note_chars: z.number().int().min(1).optional().describe('Cap each free-text field at N characters.'),
     via: z.enum(['post', 'get']).optional().describe('Vendor transport (get caps the URL at 2048 chars).'),
     format: z.enum(['json', 'tsv']).optional().describe('tsv: the table as data.tsv, items omitted.'),

package/dist/tools/scope-guard.d.ts

@@ -5,7 +5,7 @@
  * not the caller's scope, and a 2,500-row page costs about a megabyte (the #233 incident). When a
  * walk is both unscoped (no `eq`/`in` condition on an id field) and large (rows walked, `min(limit, latest)`, over
  * {@link UNSCOPED_WALK_THRESHOLD}), the guard spends ONE `<resource>.count` with the same filter:
- * a count over the threshold is refused with the typed `SCOPE_REQUIRED` outcome (needs_input) naming
+ * a count over the threshold is refused with the typed `SCOPE_REQUIRED` refusal (a recoverable error, next supply_input; #243) naming
  * the count and the fix; `acknowledgeUnscoped: true` overrides.
  *
  * Fail OPEN: a count that cannot be read (a vendor error, an unreadable shape) lets the walk run and
@@ -19,9 +19,10 @@ import type { ToolContext } from './context.js';
 export declare const UNSCOPED_WALK_THRESHOLD = 500;
 /** The bag key that overrides the guard (autotask_read args[0]); autotask_query spells it `acknowledge_unscoped`. */
 export declare const ACK_KEY = "acknowledgeUnscoped";
-/** Typed refusal of an unscoped walk: answers the needs_input envelope (reason SCOPE_REQUIRED) or a typed slot error. */
+/** Typed refusal of an unscoped walk: an error envelope (reason SCOPE_REQUIRED, next supply_input) or a typed slot error. */
 export declare class ScopeRequiredError extends Error {
     readonly code: "SCOPE_REQUIRED";
+    readonly field = "filter";
     readonly count: number;
     readonly threshold: number;
     readonly operation: string;

package/dist/tools/scope-guard.js

@@ -4,21 +4,24 @@ import { RATE_CODES } from './reasons.js';
 export const UNSCOPED_WALK_THRESHOLD = 500;
 /** The bag key that overrides the guard (autotask_read args[0]); autotask_query spells it `acknowledge_unscoped`. */
 export const ACK_KEY = 'acknowledgeUnscoped';
-/** Typed refusal of an unscoped walk: answers the needs_input envelope (reason SCOPE_REQUIRED) or a typed slot error. */
+/** Typed refusal of an unscoped walk: an error envelope (reason SCOPE_REQUIRED, next supply_input) or a typed slot error. */
 export class ScopeRequiredError extends Error {
     code = 'SCOPE_REQUIRED';
+    field = 'filter';
     count;
     threshold;
     operation;
     suggestedAction;
     details;
     constructor(operation, count, ackName) {
-        super(`${operation}: no id-field filter and ${count} rows match (over ${UNSCOPED_WALK_THRESHOLD}): a tenant-wide walk in vendor id order, not your scope.`);
+        const suggestedAction = `Filter on resolved ids (companyID, contractID, ticketID, resourceID with op eq or in), or autotask_query group_by, sum or count for totals, or pass ${ackName}: true to walk it anyway.`;
+        // within the 200-char message bound (MAX_ERROR_MESSAGE_CHARS) whatever the resource name: data.operation names the op
+        super(`${count} rows match with no id filter (over ${UNSCOPED_WALK_THRESHOLD}). Filter on companyID, contractID, ticketID or resourceID (eq or in; time entries: ticket.companyID) and call again, or pass ${ackName}: true.`);
         this.operation = operation;
         this.count = count;
         this.threshold = UNSCOPED_WALK_THRESHOLD;
         this.details = { count, threshold: UNSCOPED_WALK_THRESHOLD };
-        this.suggestedAction = `Filter on resolved ids (companyID, contractID, ticketID, resourceID with op eq or in), or autotask_query group_by, sum or count for totals, or pass ${ackName}: true to walk it anyway.`;
+        this.suggestedAction = suggestedAction;
     }
 }
 /**

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.38.2";
+export declare const SERVER_VERSION = "0.38.4";

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.38.2';
+export const SERVER_VERSION = '0.38.4';
 //# 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.38.2";
+    readonly version: "0.38.4";
     readonly mcpProtocolBaseline: "2026-07-28";
     readonly legacyProtocolFallback: "2025-11-25";
 };

package/dist/tools/server.js

@@ -79,7 +79,7 @@ Routing:
 - Who am I, version, budget, clock: autotask_tenant_status.
 - Anything else: autotask_catalog q, then autotask_describe operation, then autotask_read.
 
-Filters: [{field, op, value}]; op is eq, noteq, gt, gte, lt, lte, beginsWith, endsWith, contains, exist, notExist, in or notIn; group with {op: "and"|"or", items: [...]}. Field names are vendor-cased: operations.fieldCatalog args [{resources:[key], fields:[names], labels:true}], not getFieldInfo. A bare object is refused. in/notIn take an array or "1,2,3". latest N returns the N newest by id and needs limit >= N.
+Filters: [{field, op, value}]; op is eq, noteq, gt, gte, lt, lte, beginsWith, endsWith, contains, exist, notExist, in or notIn; group with {op: "and"|"or", items: [...]}. Field names are vendor-cased: operations.fieldCatalog args [{resources:[key], fields:[names], labels:true}], not getFieldInfo. A bare object is refused. in/notIn take an array or "1,2,3".
 Dates: UTC ISO-8601; dateWorked is a YYYY-MM-DD date, never converted.
 Scope every *.query by resolved company/contract ids; time entries have none: filter ticket.companyID. Unscoped is a tenant-wide walk, refused above 500 rows unless acknowledge_unscoped (query) or acknowledgeUnscoped (read). Totals: autotask_query group_by/sum (same scope); time: both hoursWorked and hoursToBill.
 A list miss is not proof of absence: verify by id.${zone}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iit-mcp-autotask",
-  "version": "0.38.2",
+  "version": "0.38.4",
   "description": "MCP server for the Autotask (Datto) PSA domain, built on the node-autotask SDK",
   "license": "MIT",
   "author": "Max Soukhomlinov",

package/server.json

@@ -1,6 +1,6 @@
 {
   "name": "iit-mcp-autotask",
-  "version": "0.38.2",
+  "version": "0.38.4",
   "description": "MCP server for the Autotask (Datto) PSA API, powered by the node-autotask SDK",
   "mcpProtocolBaseline": "2026-07-28",
   "legacyProtocolFallback": "2025-11-25",

package/skills/contract-profitability.md

@@ -6,7 +6,7 @@ profile: readonly
 description: Monthly P&L of one contract: revenue, costs, profit, margin, coverage gaps and warnings.
 when_not_to_use: unbilled work of a company (unbilled-work-review); the contract record alone (autotask_contract_full_profile)
 ops: ["autotask_query:contracts.query", "autotask_read:contracts.profitability", "autotask_query:tickets.query"]
-inputs: {"type": "object", "required": ["contract"], "properties": {"contract": {"type": ["string", "integer"], "description": "Contract name or numeric id"}, "dateFrom": {"type": "string", "description": "YYYY-MM-DD window start. Pass both dateFrom and dateTo, or neither: with neither, the server defaults the window to the last full calendar month (UTC); exactly one is refused (needs_input)."}, "dateTo": {"type": "string", "description": "YYYY-MM-DD window end, at most 36 months after dateFrom (the both-or-neither rule of dateFrom applies)"}}}
+inputs: {"type": "object", "required": ["contract"], "properties": {"contract": {"type": ["string", "integer"], "description": "Contract name or numeric id"}, "dateFrom": {"type": "string", "description": "YYYY-MM-DD window start. Pass both dateFrom and dateTo, or neither: with neither, the server defaults the window to the last full calendar month (UTC); exactly one is refused (INPUT_INVALID)."}, "dateTo": {"type": "string", "description": "YYYY-MM-DD window end, at most 36 months after dateFrom (the both-or-neither rule of dateFrom applies)"}}}
 outcomes: ["ok", "needs_input", "ambiguous", "error"]
 hazards: ["money is in the internal currency", "annual units count in their start month"]
 related: ["unbilled-work-review"]
@@ -18,7 +18,7 @@ eval: evals/contract-profitability.json
 ## Inputs
 
 - `contract` (name or id) from the caller's task; a missing `contract` is `needs_input` for it.
-- The window: `dateFrom` and `dateTo` (YYYY-MM-DD), both or neither. With neither, the read path defaults the window to the last full calendar month (UTC) and names it in the result's `windowNote`; exactly one side is refused (`needs_input` for both days). The usual 12-month window is passed as both days.
+- The window: `dateFrom` and `dateTo` (YYYY-MM-DD), both or neither. With neither, the read path defaults the window to the last full calendar month (UTC) and names it in the result's `windowNote`; exactly one side is refused (`INPUT_INVALID` naming the missing day). The usual 12-month window is passed as both days.
 
 ## Steps
 
@@ -39,7 +39,7 @@ Profit equals revenue minus `total_cost` for each month you report; the contract
 ## Failure and rollback
 
 - `INPUT_INVALID` (window inverted or over 36 months): fix the dates and call again.
-- `needs_input` for the window (exactly one of `dateFrom`/`dateTo`): pass both days, or neither (the default last full calendar month, UTC).
+- `INPUT_INVALID` on `args[1].dateFrom` or `args[1].dateTo` (exactly one of them given): pass both days, or neither (the default last full calendar month, UTC), and call again.
 - `TARGET_NOT_FOUND` for the contract: `needs_input` for `contract`.
 - Other `error`: return it unchanged.