iit-mcp-autotask 0.38.3 → 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
@@ -780,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

@@ -53,9 +53,10 @@ export function buildQuery(ctx) {
             }
             // #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).
+            // 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)) {
-                throw new InputInvalidError('query: filter is missing or empty; call again with a scope condition such as {field: "companyID", op: "eq", value: "<id>"} (time_entries: ticket.companyID), or {field: "id", op: "exist"} for the whole entity', 'filter');
+                // 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) {

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/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.3";
+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.3';
+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.3";
+    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.3",
+  "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.3",
+  "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.