iit-mcp-autotask 0.29.0 → 0.30.0

package/capabilities.json

@@ -340,7 +340,7 @@
     },
     {
       "id": "autotask.generic.write",
-      "description": "Preview a create, update or delete by exact key and target ids (never names): validates, reads the target, checks the policy and returns a plan handle and diff. Changes nothing; autotask_apply executes the plan.",
+      "description": "Preview any write (create, update, delete or a composite helper) by exact key, args in declaration order, ids never names: validates, reads the target, returns a plan and diff. A composite op echoes its args only, no field diff.",
       "mcpPrimitive": "tool",
       "toolName": "autotask_write",
       "type": "write",
@@ -378,7 +378,7 @@
       "autotask_describe",
       "autotask_read"
     ],
-    "backingRegistryOperations": 1278,
+    "backingRegistryOperations": 1279,
     "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/access/write-env.js

@@ -12,13 +12,12 @@ const EXACT = /^[A-Za-z][A-Za-z0-9_]*\.[A-Za-z][A-Za-z0-9]*$/;
 const FIELD = /^[A-Za-z][A-Za-z0-9_]*$/;
 const LIMIT = /^([1-9]\d{0,5})\/(h|d)$/;
 const TRUSTED = /^[A-Za-z0-9._:-]{1,200}$/;
-/** Operations the preview/apply path can serve: real writes with a snapshot-able shape. */
+/** Operations the preview/apply path serves: every write and destructive record the hard rules do not refuse. */
 const servable = () => {
     const out = new Map();
     for (const r of RECORDS) {
-        const shape = writeShape(r);
-        if (hardRuleFor(r.id, r).never === undefined && shape !== undefined)
-            out.set(r.id, shape);
+        if (hardRuleFor(r.id, r).never === undefined)
+            out.set(r.id, writeShape(r));
     }
     return out;
 };
@@ -55,9 +54,9 @@ function parseWrite(raw, ops, problems) {
             continue;
         }
         if (exact && !ops.has(pattern)) {
-            const rec = recordById(pattern);
-            const never = hardRuleFor(pattern, rec).never;
-            problems.push(`${pattern}: ${never ?? 'the argument shape is not supported by preview/apply'}`);
+            // every write is servable, so this is a read, a credential-minting op or an unknown key
+            const never = hardRuleFor(pattern, recordById(pattern)).never;
+            problems.push(`${pattern}: ${never ?? 'not a served write'}`);
             continue;
         }
         if (exact && mode === 'allow' && hardRuleFor(pattern, recordById(pattern)).approval === 'always') {

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

@@ -102,7 +102,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 = "7004015258f8bd5b6a0fd1b27fca39511af3c4b1c190804af8a615f8741b5670";
+export declare const BUILT_AGAINST_PLAN_HASH = "48ee23d80fad38531486c52af40f388df810d0ee4b8d368f7d18628e276578d0";
 /**
  * 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

@@ -126,7 +126,7 @@ export const TOOL_DESCRIPTIONS = {
     autotask_contract_full_profile: 'One contract with services, billing rules, the 50 newest charges and service units. Monthly P&L: autotask_read (guide: contract-profitability).',
     autotask_quote_get: 'One quote with its line items in one call. A list of quotes: autotask_read quotes.query.',
     autotask_invoice_get: 'One invoice: the record (line data rides on it), or the html, xml or pdf export (format; in-band as a base64 document, or raw to output_path on stdio). A list: autotask_read invoices.query.',
-    autotask_write: 'Preview a create, update or delete by exact key and target ids (never names): validates, reads the target, checks the policy and returns a plan handle and diff. Changes nothing; autotask_apply executes the plan.',
+    autotask_write: 'Preview any write (create, update, delete or a composite helper) by exact key, args in declaration order, ids never names: validates, reads the target, returns a plan and diff. A composite op echoes its args only, no field diff.',
     autotask_apply: 'Execute exactly one previewed plan (plan handle from autotask_write). Re-applying is safe: a recorded outcome replays. After an unknown outcome re-read the target; never re-apply blindly.',
 };
 /** The served description for one registered tool. */
@@ -164,7 +164,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 = '7004015258f8bd5b6a0fd1b27fca39511af3c4b1c190804af8a615f8741b5670';
+export const BUILT_AGAINST_PLAN_HASH = '48ee23d80fad38531486c52af40f388df810d0ee4b8d368f7d18628e276578d0';
 /**
  * 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/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.29.0";
+export declare const SERVER_VERSION = "0.30.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.29.0';
+export const SERVER_VERSION = '0.30.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.29.0";
+    readonly version: "0.30.0";
     readonly mcpProtocolBaseline: "2026-07-28";
     readonly legacyProtocolFallback: "2025-11-25";
 };

package/dist/tools/write/apply-phases.d.ts

@@ -79,6 +79,8 @@ export interface Sent {
         correlationId?: string;
         manualAction?: Record<string, unknown>;
     } | undefined;
+    /** The generic `call` shape's own SDK result (there is no shaped outcome to report instead). */
+    callResult?: unknown;
 }
 /** `apply_start`, then the one SDK write under the cap. Never returns a ToolReturn: the outcome is always a ledger entry. */
 export declare function send(a: ApplyCtx, s: {
@@ -97,4 +99,5 @@ export declare function respond(a: ApplyCtx, r: {
     entry: LedgerEntry;
     error: unknown;
     moveResult: Sent['moveResult'];
+    callResult?: unknown;
 }): Promise<ToolReturn>;

package/dist/tools/write/apply-phases.js

@@ -235,6 +235,7 @@ export async function send(a, s) {
     let entry;
     let error;
     let moveResult;
+    let callResult;
     try {
         // ponytail: past the cap the write keeps running and its late answer is not recorded; the
         // outcome stays unknown (cooldown, re-read) rather than racing a second ledger update.
@@ -266,6 +267,8 @@ export async function send(a, s) {
             moveResult = m === null ? undefined : { status: String(m.status), correlationId: typeof m.correlationId === 'string' ? m.correlationId : undefined, ...(m.manualAction !== undefined ? { manualAction: { action: m.manualAction.action, uiLink: m.manualAction.uiLink, reason: m.manualAction.reason } } : {}) };
         }
         else {
+            if (shape === 'call')
+                callResult = result;
             const id = result?.id;
             const createdId = typeof id === 'number' || typeof id === 'string' ? id : undefined;
             entry = {
@@ -303,7 +306,7 @@ export async function send(a, s) {
     finally {
         clearTimeout(timer);
     }
-    return { entry, error, moveResult };
+    return { entry, error, moveResult, ...(shape === 'call' ? { callResult: callResult ?? null } : {}) };
 }
 /** Record the outcome (under the op lock) and run the post-write standing check. Throws a ConfigError by design; never caught here. */
 export function recordResult(a, entry, confirmation) {
@@ -344,13 +347,16 @@ export function recordResult(a, entry, confirmation) {
 /** Answer from the recorded entry: failures, moves, and the read-backs of creates and updates. */
 export async function respond(a, r) {
     const { ctx, store, plan } = a;
-    const { record, shape, entry, error, moveResult } = r;
+    const { record, shape, entry, error, moveResult, callResult } = r;
     if (entry.state !== 'succeeded') {
         const data = error === undefined ? {} : { error: honestError(typedErrorPayload(error, ctx.correlationId, requestSecrets(ctx)), error, entry) };
         return outcomeAnswer(plan, entry, { replayed: false, data });
     }
     if (shape === 'move')
         return outcomeAnswer(plan, entry, { replayed: false, ...(moveResult !== undefined ? { data: { move: moveResult } } : {}) });
+    // The generic shape answers the operation's own result (the ledger records ids and the outcome, never a payload)
+    if (shape === 'call')
+        return outcomeAnswer(plan, entry, { replayed: false, result: callResult ?? null });
     // A create reads its stored record back (one governed get); a failed read-back never fails the write.
     if (shape.startsWith('create') && entry.outcome?.id !== undefined) {
         try {

package/dist/tools/write/apply.js

@@ -56,7 +56,7 @@ export function buildApply(ctx) {
                     return claimed;
                 const sent = await send(a, { confirmation, record, shape, snap, base: claimed.ok.base });
                 recordResult(a, sent.entry, confirmation);
-                return respond(a, { record, shape, entry: sent.entry, error: sent.error, moveResult: sent.moveResult });
+                return respond(a, { record, shape, entry: sent.entry, error: sent.error, moveResult: sent.moveResult, callResult: sent.callResult });
             });
         },
     };

package/dist/tools/write/outcome.d.ts

@@ -14,9 +14,10 @@ export declare function notPersistedAnswer(plan: PlanRecord, entry: LedgerEntry,
     record?: unknown;
     unrecorded?: boolean;
 }): ToolReturn;
-/** The envelope for a recorded (or just recorded) outcome. */
+/** The envelope for a recorded (or just recorded) outcome. `result` overrides the ledger id a success reports. */
 export declare function outcomeAnswer(plan: PlanRecord, entry: LedgerEntry, extra: {
     replayed: boolean;
     data?: Record<string, unknown>;
     summary?: string;
+    result?: unknown;
 }): ToolReturn;

package/dist/tools/write/outcome.js

@@ -30,7 +30,7 @@ export function notPersistedAnswer(plan, entry, fields, extra) {
         notPersisted: fields,
     }, { plan: plan.handle, planHash: plan.planHash, ...(extra.replayed ? { replayed: true } : {}), summary: `${plan.op} reached the vendor (HTTP success) but ${fields.join(', ')} did not change.${extra.unrecorded === true ? ' This miss could not be recorded (the state lock was busy): a replay of this plan will answer plain ok, so re-read the record before relying on it.' : ''}` });
 }
-/** The envelope for a recorded (or just recorded) outcome. */
+/** The envelope for a recorded (or just recorded) outcome. `result` overrides the ledger id a success reports. */
 export function outcomeAnswer(plan, entry, extra) {
     const meta = { plan: plan.handle, planHash: plan.planHash, ...(extra.replayed ? { replayed: true } : {}) };
     const base = { operation: plan.op, targets: plan.targets, outcome: entry.state === 'sending' ? 'unknown' : entry.state, ...extra.data };
@@ -48,7 +48,9 @@ export function outcomeAnswer(plan, entry, extra) {
         });
     }
     if (entry.state === 'succeeded') {
-        return answer('ok', 'proceed', [], { ...base, result: entry.outcome?.id === undefined ? {} : { id: entry.outcome.id } }, { ...meta, summary: extra.summary ?? `${plan.op} succeeded${extra.replayed ? ' (recorded outcome replayed; nothing was sent again)' : ''}.` });
+        // a generic `call` op reports its own SDK result; a shaped one reports the ledger id
+        const result = 'result' in extra ? extra.result : entry.outcome?.id === undefined ? {} : { id: entry.outcome.id };
+        return answer('ok', 'proceed', [], { ...base, result }, { ...meta, summary: extra.summary ?? `${plan.op} succeeded${extra.replayed ? ' (recorded outcome replayed; nothing was sent again)' : ''}.` });
     }
     if (entry.outcome?.code === 'MOVE_RESOLVED') {
         // issue #131: a person cleared this move by hand; a copy may exist, so never say "nothing was written"

package/dist/tools/write/parse.d.ts

@@ -3,12 +3,29 @@ import type { Reason } from '../reasons.js';
 import type { WriteShape } from '../../write/hard-rules.js';
 import type { PlanTargets } from '../../write/store.js';
 export declare const SHAPE_ARGS: Record<WriteShape, string[]>;
+/** The argument names of the generic `call` shape that name the record's own id (the snapshot's target). */
+export declare const CALL_ID_ARGS: ReadonlySet<string>;
+/** The argument names of the generic `call` shape that name a company the write touches (a scope fact). */
+export declare const CALL_COMPANY_ARGS: ReadonlySet<string>;
+/** A positive integer id, or a canonical integer string (the registry accepts both forms for ids). */
+export declare function asId(value: unknown): number | undefined;
 export interface ParsedArgs {
     args: unknown[];
     targets: PlanTargets;
     data?: Record<string, unknown>;
 }
+/**
+ * The generic `call` shape (issue #191): the record's own declared arguments, in registry order, sent
+ * to the SDK op unchanged. There is no field-level snapshot to validate against, so the arguments are
+ * checked by the SDK's OWN pre-request validator (`validateDispatchArgs`: arity, required args, loose
+ * types, zero wire) and by the same payload hygiene the data object gets. Ids stay ids where the
+ * registry names one; an object argument is a payload and its references are scope facts.
+ */
+export declare function parseCallArgs(record: CapabilityRecord, raw: unknown[]): ParsedArgs | Reason;
 /** Validate the positional args against the shape; ids are positive integers, never names. */
 export declare function parseArgs(shape: WriteShape, record: CapabilityRecord, raw: unknown[]): ParsedArgs | Reason;
-/** The ledger's key for a target: the record for an update or delete, the payload for a create. */
+/**
+ * The ledger's key for a target: the record for an update or delete, the payload for a create, and for
+ * the generic `call` shape the record (or parent) it names — or, when it names none, the arguments.
+ */
 export declare function targetKeyOf(shape: WriteShape, targets: PlanTargets, args: unknown[]): string;

package/dist/tools/write/parse.js

@@ -1,4 +1,5 @@
 /** Argument parsing and the target key of a write (issue #89). */
+import { validateDispatchArgs } from 'node-autotask/operations';
 import { stripUntrustedDeep } from 'node-autotask/untrusted';
 import { hashOf } from '../../write/canonical.js';
 import { reason } from './common.js';
@@ -14,9 +15,89 @@ export const SHAPE_ARGS = {
     delete: ['id'],
     delete_child: ['parentId', 'id'],
     move: ['sourceId', 'toTicketId'],
+    // the generic shape takes the record's own declared arguments, in the registry's order (below)
+    call: [],
 };
+/** The argument names of the generic `call` shape that name the record's own id (the snapshot's target). */
+export const CALL_ID_ARGS = new Set(['id', 'sourceId', 'sourceContactId']);
+/** The argument names of the generic `call` shape that name a company the write touches (a scope fact). */
+export const CALL_COMPANY_ARGS = new Set(['companyID', 'companyId', 'destinationCompanyId', 'destinationCompanyID']);
+/** A positive integer id, or a canonical integer string (the registry accepts both forms for ids). */
+export function asId(value) {
+    if (typeof value === 'number' && Number.isSafeInteger(value) && value > 0)
+        return value;
+    if (typeof value === 'string' && /^\d+$/.test(value)) {
+        const n = Number(value);
+        return Number.isSafeInteger(n) && n > 0 ? n : undefined;
+    }
+    return undefined;
+}
+/**
+ * The generic `call` shape (issue #191): the record's own declared arguments, in registry order, sent
+ * to the SDK op unchanged. There is no field-level snapshot to validate against, so the arguments are
+ * checked by the SDK's OWN pre-request validator (`validateDispatchArgs`: arity, required args, loose
+ * types, zero wire) and by the same payload hygiene the data object gets. Ids stay ids where the
+ * registry names one; an object argument is a payload and its references are scope facts.
+ */
+export function parseCallArgs(record, raw) {
+    const names = Object.keys(record.inputSchema);
+    const stripped = stripUntrustedDeep(raw);
+    if (stripped.length > names.length) {
+        return reason('INPUT_INVALID', `${record.id} takes at most ${names.length} arg(s): [${names.join(', ')}]`, 'args');
+    }
+    const required = names.filter((n) => record.inputSchema[n]?.required === true);
+    if (stripped.length < required.length) {
+        return reason('INPUT_INVALID', `${record.id} requires ${required.length} arg(s): [${required.join(', ')}] (declared: [${names.join(', ')}])`, 'args');
+    }
+    const out = [];
+    const targets = { resource: record.resource };
+    for (const [i, name] of names.entries()) {
+        const value = stripped[i];
+        if (value === undefined) {
+            out.push(undefined);
+            continue;
+        }
+        const where = `args.${i}`;
+        const payload = value !== null && typeof value === 'object' && !Array.isArray(value);
+        if (payload) {
+            const dup = caseDuplicate(value, where);
+            if (dup !== undefined)
+                return reason('INPUT_INVALID', `${dup}: payload keys are plain ASCII field names (letters, digits, underscore), one key per field whatever its case`, dup);
+            const copied = sanitisedArtefact(value, where);
+            if (copied !== undefined)
+                return reason('INPUT_INVALID', `${copied} carries a copied-artefact class: a typed HTML entity sequence (&lt; &gt; &amp;), a truncation marker (server or note_chars form), or a wrapper tag in this server's exact spelling. Leave it out or send a new value.`, copied);
+        }
+        const cleaned = cleanPayload(value);
+        if (payload) {
+            const leftover = leftoverCombiningMark(cleaned, where);
+            if (leftover !== undefined) {
+                return reason('INPUT_INVALID', `${leftover} carries a combining mark with no precomposed form (for example a lone U+0301); the vendor stores such a character as a different one, so the write would not round-trip. Send the precomposed character instead`, leftover);
+            }
+        }
+        out.push(cleaned);
+        const id = asId(cleaned);
+        if (id !== undefined && CALL_ID_ARGS.has(name))
+            targets.id = id;
+        else if (id !== undefined && name === 'parentId')
+            targets.parentId = id;
+    }
+    // a trailing absent option is simply absent (a stored `undefined` would read back as null)
+    let last = out.length - 1;
+    while (last >= 0 && out[last] === undefined)
+        last--;
+    const args = out.slice(0, last + 1);
+    try {
+        validateDispatchArgs(record, args);
+    }
+    catch (err) {
+        return reason('INPUT_INVALID', `${record.id}: ${err.message}`, 'args');
+    }
+    return { args, targets };
+}
 /** Validate the positional args against the shape; ids are positive integers, never names. */
 export function parseArgs(shape, record, raw) {
+    if (shape === 'call')
+        return parseCallArgs(record, raw);
     const names = SHAPE_ARGS[shape];
     if (raw.length !== names.length)
         return reason('INPUT_INVALID', `${record.id} takes ${names.length} arg(s): [${names.join(', ')}]`, 'args');
@@ -60,10 +141,20 @@ export function parseArgs(shape, record, raw) {
     }
     return data === undefined ? { args: out, targets } : { args: out, targets, data };
 }
-/** The ledger's key for a target: the record for an update or delete, the payload for a create. */
+/**
+ * The ledger's key for a target: the record for an update or delete, the payload for a create, and for
+ * the generic `call` shape the record (or parent) it names — or, when it names none, the arguments.
+ */
 export function targetKeyOf(shape, targets, args) {
     if (shape.startsWith('create'))
         return `${targets.resource}:create:${hashOf(args).slice(7, 23)}`;
+    if (shape === 'call') {
+        if (targets.id !== undefined)
+            return `${targets.resource}:${targets.parentId === undefined ? '' : `${targets.parentId}/`}${targets.id}`;
+        if (targets.parentId !== undefined)
+            return `${targets.resource}:parent:${targets.parentId}`;
+        return `${targets.resource}:call:${hashOf(args).slice(7, 23)}`;
+    }
     return `${targets.resource}:${targets.parentId === undefined ? '' : `${targets.parentId}/`}${targets.id}`;
 }
 //# sourceMappingURL=parse.js.map

package/dist/tools/write/preview.js

@@ -11,6 +11,17 @@ import { parseArgs } from './parse.js';
 import { honestImpact } from './payload.js';
 import { takeSnapshot, moveSummary } from './snapshot.js';
 import { unresolvedReason, markedDiff, deriveFacts } from './facts.js';
+/**
+ * The generic `call` shape has no field-level snapshot (issue #191): no vendor reads establish what the
+ * op will change, so the preview states the arguments it will send — unchanged — and an impact that
+ * claims nothing it cannot know. It is one call, and this server cannot undo it.
+ */
+// A composite op decides its own steps, so the preview must not claim a record
+// count or a single-record scope: `affected: null` + scope 'composite' is the
+// honest answer (operations.recovery can delete up to `limit` rows;
+// resources.transferOwnership moves a whole book of work).
+const CALL_IMPACT = { affected: null, scope: 'composite', reversible: false };
+const CALL_WARNING = 'this operation has no field-level snapshot: the preview echoes the arguments as they will be sent and the scope reads behind them; autotask_apply sends exactly these arguments to the SDK operation. The blast radius is the op own: it can affect more than one record - check the operation arguments';
 /** Blocked state, the hard rules and the AUTOTASK_WRITE row, then the args: each answers before any read. */
 function admit(r) {
     const { ctx, store, loaded, args, op, audit } = r;
@@ -80,7 +91,11 @@ async function snapshot(r, a) {
 /** The SDK dry run: its validation and the diff (no vendor write is issued). */
 async function dryRun(r, a) {
     const { ctx, op, audit, signal } = r;
-    const { record, parsed } = a;
+    const { record, parsed, shape } = a;
+    // The generic shape has no dry run to ask for (the op decides its own steps): the preview answers
+    // from the arguments and the snapshot, and the apply is the one call that sends them.
+    if (shape === 'call')
+        return { ok: { wouldApply: true, warnings: [CALL_WARNING] } };
     const confirm = record.effect === 'destructive' || record.flags.includes('requiresApproval') ? { confirm: op } : {};
     const invoke = record.effect === 'destructive' ? ctx.ops.invokeDelete : ctx.ops.invokeWrite;
     let dry;
@@ -143,7 +158,8 @@ function evaluatePhase(r, a, snap, dry, resource) {
         hazards: decision.hazards,
         diff: markedDiff(dry.diff),
         warnings: (dry.warnings ?? []).slice(0, 20).map((x) => String(x)),
-        impact: honestImpact(dry.impact, shape),
+        impact: shape === 'call' ? CALL_IMPACT : honestImpact(dry.impact, shape),
+        ...(shape === 'call' ? { dispatch: 'sdk-op', args: parsed.args } : {}),
         ...(resource !== undefined ? { resource } : {}),
         ...(shape === 'move' ? { move: moveSummary(record, parsed.targets, snap.current, dry.data, facts) } : {}),
     };

package/dist/tools/write/snapshot.d.ts

@@ -3,7 +3,7 @@ import type { ToolContext } from '../context.js';
 import type { Reason } from '../reasons.js';
 import type { WriteFacts } from '../../write/evaluate.js';
 import type { PlanTargets } from '../../write/store.js';
-import type { ParsedArgs } from './parse.js';
+import { type ParsedArgs } from './parse.js';
 /** id references that lead to a record's company when it has no companyID of its own. */
 export declare const ANCHORS: ReadonlyArray<[string, string]>;
 /**
@@ -36,6 +36,15 @@ export interface Snapshot {
         duplicateIds: unknown[];
     };
 }
+/**
+ * The generic `call` snapshot (issue #191): there is no known target/data signature, so the record's
+ * own declared arguments decide what is read. A named id (`id`, `sourceId`, `sourceContactId`) is the
+ * record's target, read and anchored; `parentId` is the parent record; a named company id is a scope
+ * fact; any object argument is a payload, and its references are scope facts (exactly as a create's
+ * data). An argument set that names no record yields no scope facts, and a company-scoped run scope
+ * then refuses the write (a write whose company cannot be established is refused).
+ */
+export declare function takeCallSnapshot(ctx: ToolContext, record: CapabilityRecord, parsed: ParsedArgs, signal: AbortSignal | undefined): Promise<Snapshot | Reason>;
 export declare function takeSnapshot(ctx: ToolContext, record: CapabilityRecord, parsed: ParsedArgs, duplicateFields: readonly string[] | undefined, signal: AbortSignal | undefined): Promise<Snapshot | Reason>;
 /** The preview block of a move (ids, fact names and field NAMES only: note text never rides it). */
 export declare function moveSummary(record: CapabilityRecord, t: PlanTargets, current: Record<string, unknown> | undefined, payload: unknown, facts: WriteFacts): Record<string, unknown>;

package/dist/tools/write/snapshot.js

@@ -1,7 +1,9 @@
 /** The pre-write snapshot (the before state), the stable facts and the forced-duplicate filters (issue #89). */
 import { relationshipMap } from 'node-autotask/operations';
 import { hashOf } from '../../write/canonical.js';
+import { writeShape } from '../../write/hard-rules.js';
 import { Cancelled, reason, isNotFound } from './common.js';
+import { CALL_COMPANY_ARGS, CALL_ID_ARGS, asId } from './parse.js';
 import { ci } from './payload.js';
 // ---------------------------------------------------------------------------
 // The snapshot: fresh reads, the companies the write touches, the duplicate query
@@ -45,15 +47,16 @@ export function hasSimpleGet(resource, ctx) {
 export function getIds(ctx, resource, parentId, id) {
     return parentId !== undefined && !hasSimpleGet(resource, ctx) ? [parentId, id] : [id];
 }
-export async function takeSnapshot(ctx, record, parsed, duplicateFields, signal) {
-    ctx.ops.freshen(ctx.client);
+/** The reader for one snapshot. Only the write's own target record is hashed in full; a referenced record is hashed by its stable facts. */
+function createReader(ctx, targetKey, signal) {
     const reads = {};
+    const hashed = {};
+    const companies = new Set();
+    const unresolved = [];
     // The write's own TARGET record is hashed in full (an update/delete must notice any change to it);
     // a record that is only REFERENCED (the ticket a time entry is logged on) is hashed by its stable
     // facts only, so a volatile stamp the first of two outstanding writes moves (lastActivityDate,
     // modified stamps) does not read as drift for the second (issue #108).
-    const targetKey = parsed.targets.id === undefined ? undefined : `${record.resource}:${getIds(ctx, record.resource, parsed.targets.parentId, parsed.targets.id).join('/')}`;
-    const hashed = {};
     const get = async (resource, ids) => {
         const key = `${resource}:${ids.join('/')}`;
         if (!(key in reads)) {
@@ -65,8 +68,6 @@ export async function takeSnapshot(ctx, record, parsed, duplicateFields, signal)
         }
         return reads[key];
     };
-    const companies = new Set();
-    const unresolved = [];
     // The positional ids for one reference's get; a parent-scoped get needs the parent id from the same record.
     const idsFor = async (resource, id, rec) => {
         if (hasSimpleGet(resource, ctx))
@@ -116,6 +117,107 @@ export async function takeSnapshot(ctx, record, parsed, duplicateFields, signal)
             await anchor(res, child, depth + 1, false);
         }
     };
+    return { reads, hashed, companies, unresolved, get, idsFor, anchor };
+}
+/**
+ * The generic `call` snapshot (issue #191): there is no known target/data signature, so the record's
+ * own declared arguments decide what is read. A named id (`id`, `sourceId`, `sourceContactId`) is the
+ * record's target, read and anchored; `parentId` is the parent record; a named company id is a scope
+ * fact; any object argument is a payload, and its references are scope facts (exactly as a create's
+ * data). An argument set that names no record yields no scope facts, and a company-scoped run scope
+ * then refuses the write (a write whose company cannot be established is refused).
+ */
+export async function takeCallSnapshot(ctx, record, parsed, signal) {
+    ctx.ops.freshen(ctx.client);
+    const { targets } = parsed;
+    const names = Object.keys(record.inputSchema);
+    const parent = await parentOf(record.resource);
+    // `parentId` names the parent record when the resource HAS a parent (a child collection); on a
+    // resource with no parent it is the record's own id (inventory_products.stockedItemsAdd's parentId
+    // IS the product). Either way it is the row this preview reads and hashes in full.
+    const selfId = targets.id ?? (parent === undefined ? targets.parentId : undefined);
+    const r = createReader(ctx, selfId === undefined ? undefined : `${record.resource}:${selfId}`, signal);
+    let current;
+    if (selfId !== undefined) {
+        const simple = hasSimpleGet(record.resource, ctx);
+        const key = `${record.resource}:${selfId}`;
+        try {
+            if (!simple && ctx.record(`${record.resource}.query`) !== undefined) {
+                // a parent-scoped get needs a parent the arguments do not name (a contact's companyID): read the
+                // row by id, as the move path does, and let the row's own references anchor it
+                const found = await ctx.ops.invokeRead(ctx.client, `${record.resource}.query`, [{ filter: [{ field: 'id', op: 'eq', value: selfId }], limit: 1 }], undefined, signal);
+                if (found === undefined)
+                    throw new Cancelled();
+                const row = (found.items ?? [])[0];
+                if (row === null || typeof row !== 'object')
+                    return reason('INPUT_INVALID', `${record.resource} ${selfId} does not exist`, 'args.0');
+                r.reads[key] = row;
+                r.hashed[key] = row;
+                current = row;
+            }
+            else if (simple) {
+                current = await r.get(record.resource, getIds(ctx, record.resource, targets.parentId, selfId));
+            }
+            else {
+                return reason('INPUT_INVALID', `${record.resource} ${selfId}: this resource's get needs a parent id and the arguments do not name one`, 'args.0');
+            }
+        }
+        catch (err) {
+            if (!isNotFound(err))
+                throw err;
+            return reason('INPUT_INVALID', `${record.resource} ${selfId} does not exist`, 'args.0');
+        }
+        await r.anchor(record.resource, current, 0, false);
+    }
+    for (const [i, name] of names.entries()) {
+        const value = parsed.args[i];
+        if (value === undefined)
+            continue;
+        const id = asId(value);
+        if (name === 'parentId') {
+            if (parent === undefined)
+                continue; // consumed as the record's own id above
+            const ids = id === undefined ? undefined : await r.idsFor(parent.resource, id, current ?? {});
+            if (ids === undefined)
+                r.unresolved.push(`${record.resource}.parent`);
+            else {
+                try {
+                    await r.anchor(parent.resource, await r.get(parent.resource, ids), 1, false);
+                }
+                catch (err) {
+                    if (!isNotFound(err))
+                        throw err;
+                    r.unresolved.push(`${record.resource}.${parent.field}`);
+                }
+            }
+            continue;
+        }
+        if (CALL_ID_ARGS.has(name))
+            continue;
+        if (CALL_COMPANY_ARGS.has(name)) {
+            if (id !== undefined)
+                r.companies.add(id);
+            continue;
+        }
+        if (value !== null && typeof value === 'object' && !Array.isArray(value))
+            await r.anchor(record.resource, value, 0, true);
+    }
+    return {
+        hash: hashOf({ reads: r.hashed }),
+        companyIds: [...r.companies].sort((a, b) => a - b),
+        unresolved: [...new Set(r.unresolved)],
+        ...(current !== undefined ? { current } : {}),
+        duplicates: 0,
+        inputs: { reads: r.hashed, duplicateIds: [] },
+    };
+}
+export async function takeSnapshot(ctx, record, parsed, duplicateFields, signal) {
+    if (writeShape(record) === 'call')
+        return takeCallSnapshot(ctx, record, parsed, signal);
+    ctx.ops.freshen(ctx.client);
+    const targetKey = parsed.targets.id === undefined ? undefined : `${record.resource}:${getIds(ctx, record.resource, parsed.targets.parentId, parsed.targets.id).join('/')}`;
+    const r = createReader(ctx, targetKey, signal);
+    const { get, idsFor, anchor, reads, hashed, unresolved, companies } = r;
     const { targets, data } = parsed;
     let current;
     if (targets.id !== undefined) {

package/dist/write/evaluate.js

@@ -18,8 +18,12 @@ export function evaluate(loaded, facts, runScope, counters) {
         return deny('OP_NOT_ALLOWED', `AUTOTASK_WRITE denies ${facts.op}`, hard.hazards);
     if (runScope === undefined)
         return deny('TARGET_NOT_IN_SCOPE', 'this principal has no run scope', hard.hazards);
-    if (!inScope(facts, runScope))
-        return deny('TARGET_NOT_IN_SCOPE', "the target's company (read from the current record) is outside the write scope of this run", hard.hazards);
+    if (!inScope(facts, runScope)) {
+        const detail = facts.companyIds.length === 0
+            ? 'this write names no record whose company could be read, so it may lie outside the write scope of this run (a run scope of {"all":true} admits it)'
+            : "the target's company (read from the current record) is outside the write scope of this run";
+        return deny('TARGET_NOT_IN_SCOPE', detail, hard.hazards);
+    }
     if (facts.blocked !== undefined)
         return deny('MOVE_UNRESOLVED', facts.blocked, hard.hazards);
     if (facts.duplicates > 0)

package/dist/write/hard-rules.d.ts

@@ -8,9 +8,12 @@
  * - `destructive` and account-wide operations (the tenant configuration resources in
  *   {@link ACCOUNT_WIDE_RESOURCES}) carry their hazard in the preview; AUTOTASK_WRITE decides their mode.
  *
- * The preview/apply path also takes only the argument shapes it can snapshot (a target id, an
- * optional parent id, a data object): {@link writeShape} names them; any other operation shape
- * (the SDK's composite helpers such as `tickets.changeStatus`) is refused when AUTOTASK_WRITE resolves.
+ * The preview/apply path serves every write. A record whose positional arguments are one of the six
+ * CRUD shapes or the move shape gets a field-level snapshot (the target record, the parent, the data
+ * object); every other record (the SDK's composite helpers: `tickets.changeStatus`,
+ * `time_entries.approve`, the `*createIfNotExists` family, ...) takes the generic `call` shape, which
+ * echoes the caller's arguments and sends exactly them. {@link writeShape} never returns undefined
+ * for a non-read record, so AUTOTASK_WRITE can name every write.
  */
 import type { CapabilityRecord } from 'node-autotask/capabilities';
 /**
@@ -29,13 +32,22 @@ export interface HardRule {
 }
 /** The hard rule for one registry record. */
 export declare function hardRuleFor(operation: string, record: CapabilityRecord | undefined): HardRule;
-/** The argument shapes the preview/apply path snapshots: the positional names, in order. */
-export type WriteShape = 'create' | 'create_child' | 'update' | 'update_child' | 'delete' | 'delete_child' | 'move';
+/**
+ * The argument shapes the preview/apply path knows: the positional names, in order.
+ * `call` is the generic fallback for every other argument signature (the SDK's composite helpers):
+ * it has no field-level snapshot, so it previews the arguments and impact instead.
+ */
+export type WriteShape = 'create' | 'create_child' | 'update' | 'update_child' | 'delete' | 'delete_child' | 'move' | 'call';
 /**
  * The only operations that may take the `move` shape (issue #107): the SDK's create-verify-delete move
- * engine. An allowlist, not the signature alone: a destructive op with no flags needs no person by hard
- * rule, so a future SDK op that happened to share the signature must not become servable as a move.
+ * engine. An allowlist, not the signature alone: a future SDK op that happened to share the signature
+ * must not be driven as a move (it takes the generic `call` shape instead, which never snapshots or
+ * recovers a source record).
  */
 export declare const MOVE_OPS: readonly string[];
-/** The write shape of a record, or `undefined` when the preview/apply path cannot snapshot it. */
-export declare function writeShape(record: CapabilityRecord): WriteShape | undefined;
+/**
+ * The write shape of a record. Every non-read record has one: the six CRUD shapes, the move shape for
+ * {@link MOVE_OPS}, and `call` for every other signature (so no write silently drops out of
+ * AUTOTASK_WRITE, issue #191).
+ */
+export declare function writeShape(record: CapabilityRecord): WriteShape;

package/dist/write/hard-rules.js

@@ -57,8 +57,9 @@ export function hardRuleFor(operation, record) {
 }
 /**
  * The only operations that may take the `move` shape (issue #107): the SDK's create-verify-delete move
- * engine. An allowlist, not the signature alone: a destructive op with no flags needs no person by hard
- * rule, so a future SDK op that happened to share the signature must not become servable as a move.
+ * engine. An allowlist, not the signature alone: a future SDK op that happened to share the signature
+ * must not be driven as a move (it takes the generic `call` shape instead, which never snapshots or
+ * recovers a source record).
  */
 export const MOVE_OPS = ['time_entries.moveToTicket', 'ticket_charges.moveToTicket'];
 const SHAPES = {
@@ -70,9 +71,13 @@ const SHAPES = {
     'delete:parentId,id': 'delete_child',
     'moveToTicket:sourceId,toTicketId': 'move',
 };
-/** The write shape of a record, or `undefined` when the preview/apply path cannot snapshot it. */
+/**
+ * The write shape of a record. Every non-read record has one: the six CRUD shapes, the move shape for
+ * {@link MOVE_OPS}, and `call` for every other signature (so no write silently drops out of
+ * AUTOTASK_WRITE, issue #191).
+ */
 export function writeShape(record) {
     const shape = SHAPES[`${record.operation}:${Object.keys(record.inputSchema).join(',')}`];
-    return shape === 'move' && !MOVE_OPS.includes(record.id) ? undefined : shape;
+    return shape === 'move' && !MOVE_OPS.includes(record.id) ? 'call' : (shape ?? 'call');
 }
 //# sourceMappingURL=hard-rules.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iit-mcp-autotask",
-  "version": "0.29.0",
+  "version": "0.30.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.29.0",
+    "node-autotask": "0.30.0",
     "zod": "^4.6.7"
   },
   "devDependencies": {

package/server.json

@@ -1,6 +1,6 @@
 {
   "name": "iit-mcp-autotask",
-  "version": "0.29.0",
+  "version": "0.30.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.29.0"
+    "versionRange": "0.30.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"