node-autotask 0.21.0 → 0.24.0

package/examples/mcp/tools-mode.ts

@@ -0,0 +1,177 @@
+/**
+ * tools-mode.ts — the autotask_read / autotask_write / autotask_delete mode
+ * tools. The ONLY write governor is `invoke` in `node-autotask/operations`;
+ * this module adds no validator and no governor of its own.
+ */
+import * as z from 'zod/v4';
+import { AutotaskConfigError, ConfirmationRequiredError } from 'node-autotask';
+import type { AutotaskError } from 'node-autotask';
+import type { CapabilityRecord } from 'node-autotask/capabilities';
+import { invokeDelete, invokeRead, invokeWrite, needsConfirmation, validateParamsBag } from 'node-autotask/operations';
+import { deepMarkUntrusted, stripUntrustedDeep } from 'node-autotask/untrusted';
+import { CATALOG, CROSS_RESOURCE_UNTRUSTED, MODE_ANNOTATIONS, RECORD_BY_ID } from './manifest.js';
+import type { ModeKind } from './manifest.js';
+import { DRY_OUTPUT, closedInput, invokeOutput } from './schemas.js';
+import { closedArgsError, dryResult, errorContent, ok } from './errors.js';
+import type { ToolContext } from './types.js';
+
+/** The mode tools refuse these BEFORE any request — the mirror the DRY-mode handler runs.
+ *  FULL100 F3: the refusals are TYPED (machine code in the served payload) — the
+ *  previous bare `Error`s served untyped failures on a surface whose error
+ *  contract is the SDK AutotaskError family. */
+function governorRefusal(rec: CapabilityRecord, operation: string, dryRun: boolean | undefined, confirm: string | undefined): AutotaskError | null {
+  if (!isWrite(rec) && dryRun === true) {
+    return new AutotaskConfigError(
+      `invoke: "${operation}" is a read — dryRun is not applicable (reads issue their request as-is)`,
+      { operation },
+    );
+  }
+  if (needsConfirmation(rec) && confirm !== operation) {
+    return new ConfirmationRequiredError(
+      `invoke: "${operation}" is ${rec.effect}${(rec.flags ?? []).includes('requiresApproval') ? ' approval-gated' : ''} and requires its confirmation flag: pass confirm: "${operation}"`,
+      { operation },
+    );
+  }
+  // Query ops are NOT refused: the SDK governor routes them to queryBounded
+  // (server-side pagination) — one call, one bounded result.
+  return null;
+}
+
+function isWrite(rec: CapabilityRecord): boolean {
+  return rec.effect !== 'read';
+}
+
+export function registerModeTools({ server, client, dry, untrustedWrap }: ToolContext): void {
+  // ==========================================================================
+  // MODE TOOLS (R1) — the registry call path split into read/write/delete
+  // modes (the autotask_invoke catch-all is gone): one shared handler core
+  // per tool — record lookup -> cross-mode refusal (the mirror of the SDK
+  // router's message) -> the governor's refusals -> the DRY-mode answer or
+  // the live dispatch through the SDK's mode-guarded wrapper (ONE
+  // implementation decides, same as today's single invoke dispatch). Their
+  // names/titles/descriptions/annotations are owned by
+  // scripts/build-tool-catalog.mjs (verbatim-checked by catalog:check).
+  // ==========================================================================
+
+  /** The registry `effect` that each mode routes (the A2 predicate, 1:1). */
+  const MODE_EFFECT: Record<ModeKind, string> = { read: 'read', write: 'write', delete: 'destructive' };
+  const EFFECT_MODE: Record<CapabilityRecord['effect'], ModeKind> = { read: 'read', write: 'write', destructive: 'delete' };
+  const MODE_TOOL_NAME: Record<ModeKind, string> = { read: 'autotask_read', write: 'autotask_write', delete: 'autotask_delete' };
+  const MODE_SDK_WRAPPER: Record<ModeKind, typeof invokeRead> = { read: invokeRead, write: invokeWrite, delete: invokeDelete };
+
+  /** Cross-mode refusal — the SAME message the SDK router throws (pre-request, zero wire). */
+  function crossModeRefusal(rec: CapabilityRecord, operation: string, mode: ModeKind): AutotaskConfigError {
+    const actual = EFFECT_MODE[rec.effect];
+    const sdk = { read: 'invokeRead', write: 'invokeWrite', delete: 'invokeDelete' }[actual];
+    const subject = rec.effect === 'write' ? 'a write' : rec.effect === 'destructive' ? 'destructive' : 'a read';
+    const target =
+      actual === 'read'
+        ? `Route it through the read mode (${sdk} / ${MODE_TOOL_NAME[actual]}).`
+        : actual === 'write'
+          ? `Route it through the write mode (${sdk} / ${MODE_TOOL_NAME[actual]} — dry-run first).`
+          : `Deletes have their own tool (${MODE_TOOL_NAME[actual]}) and require confirm: "${operation}".`;
+    return new AutotaskConfigError(
+      `invoke: "${operation}" is ${subject} (effect=${rec.effect}) — refused on the ${mode} path (${MODE_TOOL_NAME[mode]} routes effect=${MODE_EFFECT[mode]} operations only). ${target}`,
+      { operation },
+    );
+  }
+
+  const registerModeTool = (mode: ModeKind) => {
+    const meta = CATALOG.metaTools.find((m) => m.name === MODE_TOOL_NAME[mode])!;
+    const modeInput = closedInput(
+      z.object({
+        operation: z.string().min(1).describe('The exact registry key (see autotask_catalog). Exact registry key — never a tool name, never fuzzy.'),
+        args: z.array(z.unknown()).default([]).describe('The method positional args, in order (e.g. [id, data] for update; [parentId, id, data] for a parent-scoped op).'),
+        ...(mode === 'read'
+          ? {}
+          : {
+              dry_run: z.boolean().optional().describe(mode === 'write'
+                ? 'Writes only: omit or pass true to travel the dry-run path first (simulated: true, the mutating request is never issued); pass false to apply.'
+                : 'Deletes travel dry-run-first: omit or pass true for the pinned envelope; pass false to apply.'),
+              confirm: z.string().optional().describe(mode === 'write'
+                ? 'For the 3 approval-gated writes: must equal the operation key exactly, or the call is refused (in BOTH dry-run and apply mode).'
+                : 'REQUIRED for every delete: must equal the operation key exactly (in BOTH dry-run and apply mode).'),
+            }),
+      }),
+    );
+    server.registerTool(
+      MODE_TOOL_NAME[mode],
+      {
+        title: meta.title,
+        description: meta.description,
+        inputSchema: modeInput.input, // issue #3: closed top level
+        outputSchema: z.union([invokeOutput(), DRY_OUTPUT]),
+        annotations: MODE_ANNOTATIONS[mode],
+        _meta: { backingOperation: `— (META tool; dispatches through node-autotask/operations invoke${mode.charAt(0).toUpperCase()}${mode.slice(1)} — the single write governor)` },
+      },
+      async (raw, extra) => {
+        // Issue #3: the closed top-level argument set — an unknown key is
+        // refused with the typed contract BEFORE the registry lookup (it is
+        // never silently dropped; the value is never echoed).
+        const closedErr = closedArgsError(raw, modeInput.validKeys);
+        if (closedErr !== null) return closedErr;
+        const args = raw as { operation: string; args: unknown[]; dry_run?: boolean; confirm?: string };
+        // ONE implementation decides whether a LIVE call is allowed: the SDK
+        // router (the mode-guarded wrapper). In DRY mode the same pre-request
+        // checks run against the same registry data + predicates, then the
+        // call stops before any request — it is reported, never issued.
+        const rec = RECORD_BY_ID.get(args.operation);
+        if (rec === undefined) {
+          return errorContent(new AutotaskConfigError(
+            `invoke: unknown operation "${args.operation}" — it is not in the capability registry (list the exact keys with autotask_catalog)`,
+            { operation: args.operation },
+          ), untrustedWrap);
+        }
+        const refusal =
+          EFFECT_MODE[rec.effect] !== mode
+            ? crossModeRefusal(rec, args.operation, mode)
+            : governorRefusal(rec, args.operation, mode === 'read' ? undefined : args.dry_run, args.confirm);
+        if (refusal !== null) {
+          return errorContent(refusal, untrustedWrap);
+        }
+        // Issue #3: the CLOSED params bag (args[0] of the query-family
+        // verbs) — the SAME SDK check the live dispatcher runs, so DRY mode
+        // refuses identically (a probe must be refused, not reported).
+        try {
+          validateParamsBag(rec, args.args);
+        } catch (err) {
+          return errorContent(err, untrustedWrap);
+        }
+        if (dry || client === null) {
+          return dryResult(args.operation);
+        }
+        try {
+          // extra.mcpReq.signal: the MCP request's cancellation reaches every SDK request (and retry wait) of this call.
+          // Issue #1 decisions: echoed values on writes — strip ONE exact
+          // outer <untrusted_content> wrapper from the string inputs on the
+          // write and filter args before the SDK call (inner text untouched).
+          // The mode tools route every effect, so the strip runs on all three
+          // (a no-op for args that carry no wrapper).
+          const cleanArgs = stripUntrustedDeep(args.args) as unknown[];
+          const result = await client.withSignal(extra.mcpReq.signal, () =>
+            MODE_SDK_WRAPPER[mode](client, args.operation, cleanArgs, mode === 'read' ? {} : { dryRun: args.dry_run, confirm: args.confirm }),
+          );
+          const simulated = (result as { simulated?: boolean } | null)?.simulated === true;
+          // Issue #1: wrap the SDK result's externally-sourced free text —
+          // envelope-shaped results are walked deeply (items[] arrays and the
+          // dry-run echo of the submitted body).
+          const projected =
+            untrustedWrap && result !== null && result !== undefined && typeof result === 'object' && !Array.isArray(result)
+              ? deepMarkUntrusted(result, CROSS_RESOURCE_UNTRUSTED)
+              : result;
+          return ok(simulated ? `Dry run of "${args.operation}" — nothing was written (simulated: true).` : `Executed "${args.operation}".`, {
+            operation: args.operation,
+            simulated,
+            result: projected,
+          });
+        } catch (err) {
+          return errorContent(err, untrustedWrap);
+        }
+      },
+    );
+  };
+
+  registerModeTool('read');
+  registerModeTool('write');
+  registerModeTool('delete');
+}

package/examples/mcp/tools-read.ts

@@ -0,0 +1,264 @@
+/**
+ * tools-read.ts — the ten registry-backed core read tools (R2/R3/R4), their
+ * live dispatch (`coreReadCall`) and the untrusted-content projection
+ * (issue #1).
+ */
+import * as z from 'zod/v4';
+import { AutotaskConfigError } from 'node-autotask';
+import type { AutotaskClient } from 'node-autotask';
+import type { CapabilityRecord } from 'node-autotask/capabilities';
+import { resolveAny, searchAcrossResources } from 'node-autotask/operations';
+import { deepMarkUntrusted, markUntrusted } from 'node-autotask/untrusted';
+import { CATALOG, RECORD_BY_ID, annotationsFor, manifestDescription, untrustedFieldsOf } from './manifest.js';
+import type { CoreToolSpec } from './manifest.js';
+import { DRY_OUTPUT, EXPAND, IDENTIFIER, LIMIT, RESOURCES, closedInput, hitsOutput, modelOutput, oneOutput, resolveAnyOutput } from './schemas.js';
+import { closedArgsError, dryResult, errorContent, ok } from './errors.js';
+import type { ToolContext } from './types.js';
+
+export function registerReadTools({ server, client, dry, untrustedWrap }: ToolContext): void {
+  // ==========================================================================
+  // CORE READ TOOLS (R2 / R3 / R4) — the ten registry-backed core tools.
+  // Descriptions are the manifest's (manifestDescription); annotations derive
+  // from the registry record. Every handler: live call, or the DRY-mode
+  // validate-and-report answer. No tool is backed by queryAll/listPages.
+  // ==========================================================================
+
+  const registerCoreRead = (spec: CoreToolSpec, schema: z.ZodType, output: (rec: CapabilityRecord) => z.ZodType, text: (v: unknown) => string) => {
+    const opId = spec.backingOperation!;
+    const rec = RECORD_BY_ID.get(opId);
+    if (rec === undefined) throw new Error(`mcp-register: core tool "${spec.tool}" has no registry record for "${opId}"`);
+    // Issue #3: closed top level — the advertised schema carries
+    // additionalProperties: false and an unknown key is refused with the
+    // typed contract (never silently dropped), DRY and live alike.
+    const coreInput = closedInput(schema);
+    server.registerTool(
+      spec.tool,
+      {
+        title: titleFor(spec.tool, rec),
+        description: manifestDescription(spec.tool, opId),
+        inputSchema: coreInput.input,
+        outputSchema: z.union([output(rec), DRY_OUTPUT]),
+        annotations: annotationsFor(rec),
+        _meta: { backingOperation: opId, requirement: spec.requirement },
+      },
+      async (args, extra) => {
+        const closedErr = closedArgsError(args, coreInput.validKeys);
+        if (closedErr !== null) return closedErr;
+        if (dry || client === null) return dryResult(opId);
+        try {
+          const value = await client.withSignal(extra.mcpReq.signal, () => coreReadCall(client, opId, args as Record<string, unknown>));
+          // Issue #1: the projection layer wraps the externally-sourced free
+          // text AFTER the call (SDK primitives keep returning raw values) —
+          // compact AND expand: true alike (the expansion is a no-op for the
+          // five workflow resources, so one path covers both). The short
+          // summary text never echoes values, so it stays unwrapped.
+          const projected = projectUntrustedResult(opId, value, untrustedWrap ? untrustedFieldsOf(rec) : []);
+          return ok(text(projected), { ...(projected as Record<string, unknown>) });
+        } catch (err) {
+          return errorContent(err, untrustedWrap);
+        }
+      },
+    );
+  };
+
+  // R2 — identify itself to the tenant.
+  registerCoreRead(
+    coreSpec('autotask_resource_who_am_i')!,
+    z.object({}),
+    oneOutput,
+    (v) => (v === null ? 'No Resource matched the configured user.' : 'Authenticated integration identified.'),
+  );
+  registerCoreRead(
+    coreSpec('autotask_version')!,
+    z.object({}),
+    modelOutput,
+    () => 'API version in use returned.',
+  );
+  registerCoreRead(
+    coreSpec('autotask_threshold_information')!,
+    z.object({}),
+    modelOutput,
+    () => 'Request-threshold status returned.',
+  );
+
+  // R3 — find a record it cannot name.
+  registerCoreRead(
+    coreSpec('autotask_resolve_any')!,
+    z.object({ identifier: IDENTIFIER, resources: RESOURCES }),
+    resolveAnyOutput,
+    (v) => `${(v as { matches: string[] }).matches.length} resource(s) matched the identifier.`,
+  );
+  registerCoreRead(
+    coreSpec('autotask_search_across_resources')!,
+    z.object({ query: z.string().min(1).describe('The free text to search for.'), resources: RESOURCES, limit: LIMIT }),
+    hitsOutput,
+    (v) => `${(v as { results: Array<{ matches: unknown[] }> }).results.reduce((n, row) => n + row.matches.length, 0)} match(es) across ${(v as { results: unknown[] }).results.length} resource(s).`,
+  );
+
+  // R4 — one resolve per workflow resource.
+  for (const spec of CATALOG.coreProfile.tools.filter((t) => t.requirement === 'R4')) {
+    registerCoreRead(
+      spec,
+      z.object({ identifier: IDENTIFIER, expand: EXPAND }),
+      oneOutput,
+      (v) => (v === null ? 'No record matched the identifier.' : 'Record resolved (id + primary fields).'),
+    );
+  }
+}
+
+/** Look up a core spec by tool name (the generated core profile is the source). */
+function coreSpec(tool: string): CoreToolSpec | undefined {
+  return CATALOG.coreProfile.tools.find((t) => t.tool === tool);
+}
+
+/** A short human-readable display name for a registry-backed core tool. */
+function titleFor(_tool: string, rec: CapabilityRecord): string {
+  switch (rec.id) {
+    case 'resources.whoAmI': return 'Identify the Integration (whoAmI)';
+    case 'version.get': return 'API Version';
+    case 'threshold_information.get': return 'Request-Threshold Status';
+    case 'operations.resolveAny': return 'Resolve Any Workflow Record';
+    case 'operations.searchAcrossResources': return 'Search Across Workflow Resources';
+    default:
+      // The five R4 workflow resolves (operation verb `resolve`):
+      return `Resolve ${entityLabel(rec.resource)}`;
+  }
+}
+
+/** The entity label for the five workflow resources (the plan apiEntity names). */
+function entityLabel(resource: string): string {
+  const labels: Record<string, string> = {
+    companies: 'Company',
+    configuration_items: 'ConfigurationItem',
+    contacts: 'Contact',
+    projects: 'Project',
+    tickets: 'Ticket',
+  };
+  return labels[resource] ?? resource;
+}
+
+/**
+ * Issue #1 projection: wrap the externally-sourced free text of a helper
+ * tool result (the marker the LLM sees around ticket titles, notes, names,
+ * UDF values — never as instructions). Applied AFTER the SDK call returns
+ * (SDK primitives keep returning raw values — projection layer only) and to
+ * BOTH the compact and the `expand: true` result (for the five workflow
+ * resources the Summary is a structural alias of the full record, so one
+ * path covers both). `fields` empty (or wrapping disabled upstream) → the
+ * value passes through unchanged.
+ *
+ * Only the DATA payload is wrapped, never the server-generated envelope
+ * (the miss note, the match counts):
+ * - R4 resolve / whoAmI: the single `record`;
+ * - resolveAny: each `results[].value`;
+ * - searchAcrossResources: each `results[].matches[]` row.
+ * (The mode tools' `result` is envelope-shaped and is walked deeply instead
+ * — see the mode-tool handler.)
+ */
+export function projectUntrustedResult(opId: string, value: unknown, fields: readonly string[]): unknown {
+  if (!Array.isArray(fields) || fields.length === 0) return value;
+  const v = value as Record<string, unknown> | null;
+  if (v === null || typeof v !== 'object' || Array.isArray(v)) return value;
+  switch (opId) {
+    case 'operations.resolveAny':
+      return {
+        ...v,
+        results: (Array.isArray(v.results) ? v.results : []).map((row) =>
+          row !== null && typeof row === 'object' && !Array.isArray(row) && 'value' in row
+            ? { ...(row as Record<string, unknown>), value: deepMarkUntrusted((row as Record<string, unknown>).value, fields) }
+            : row,
+        ),
+      };
+    case 'operations.searchAcrossResources':
+      return {
+        ...v,
+        results: (Array.isArray(v.results) ? v.results : []).map((r) =>
+          r !== null && typeof r === 'object' && !Array.isArray(r)
+            ? {
+                ...(r as Record<string, unknown>),
+                matches: (Array.isArray((r as Record<string, unknown>).matches) ? ((r as Record<string, unknown>).matches as unknown[]) : []).map(
+                  (m) => (m !== null && typeof m === 'object' && !Array.isArray(m) ? markUntrusted(m as Record<string, unknown>, fields) : m),
+                ),
+              }
+            : r,
+        ),
+      };
+    default:
+      // R4 resolve / whoAmI: the single `record` (absent/null records pass
+      // through; non-record records are opaque).
+      if ('record' in v) {
+        return {
+          ...v,
+          record:
+            v.record !== null && typeof v.record === 'object' && !Array.isArray(v.record)
+              ? markUntrusted(v.record as Record<string, unknown>, fields)
+              : v.record,
+        };
+      }
+      return value;
+  }
+}
+
+/** The live-mode dispatch for the ten registry-backed core tools (helper tier only). Exported as the
+ * test seam (S12-E2E D1: the R4 miss-shape contract is pinned without a live tenant). */
+export async function coreReadCall(client: AutotaskClient, opId: string, args: Record<string, unknown>): Promise<unknown> {
+  switch (opId) {
+    case 'resources.whoAmI': {
+      const record = await client.resources.whoAmI();
+      return { found: record !== null, record };
+    }
+    case 'version.get':
+      return { model: await client.version.get() };
+    case 'threshold_information.get':
+      return { model: await client.thresholdInformation.get() };
+    case 'operations.resolveAny':
+      return resolveAny(client, args.identifier as number | string, { resources: args.resources as string[] | undefined });
+    case 'operations.searchAcrossResources':
+      return searchAcrossResources(client, args.query as string, {
+        resources: args.resources as string[] | undefined,
+        limit: args.limit as number | undefined,
+      });
+    default:
+      break;
+  }
+  // The five R4 workflow resolves share the same shape (helper tier, one call):
+  // route through the client accessor named by the resource key.
+  const resource = opId.split('.')[0]!;
+  const holder = (client as unknown as Record<string, {
+    resolveDetailed: (id: number | string) => Promise<{ value: unknown; triedFields?: string[] }>;
+  } | undefined>)[camelAccessor(resource)];
+  if (holder === undefined) {
+    // FULL100 F6 (second-pass MINOR): typed, not bare — the served-surface
+    // contract (F3) is that every isError the MCP layer serves carries a
+    // machine code; this branch is unreachable on the current registry
+    // (every read op's resource has a client accessor — sweep-verified) but
+    // must not regress the contract if the registry ever outgrows the client.
+    throw new AutotaskConfigError(
+      `mcp-register: the client exposes no accessor for resource "${resource}" (the SDK governor would refuse this dispatch too)`,
+      { operation: opId, suggestedAction: 'Rebuild the generated surface (npm run mcp:project) or the registry drifted from the client.' },
+    );
+  }
+  // resolveDetailed (not the plain resolve): a STRING miss returns value:null with the
+  // triedFields the exact match was run against — the tool carries that as the typed
+  // `miss` payload (a miss is never a bare zero). A numeric id miss still propagates
+  // the vendor's own typed NOT_FOUND (a miss that carries a fault is not a miss).
+  void args.expand; // the Summary is a structural alias of the full record (no-op, as before)
+  const res = await holder.resolveDetailed(args.identifier as number | string);
+  if (res.value === null) {
+    const tried = res.triedFields ?? [];
+    return {
+      found: false,
+      record: null,
+      miss: {
+        triedFields: tried,
+        note: `Exact match only against the primary text field(s): ${tried.join(', ') || 'id'}. No record matched — other identifier forms (e.g. an email address) are not tried by resolve; use the resource's dedicated lookup op where one exists (see autotask_catalog).`,
+      },
+    };
+  }
+  return { found: true, record: res.value };
+}
+
+/** snake_case resource key -> the client accessor name (the SDK's camelKey rule). */
+function camelAccessor(resource: string): string {
+  return resource.split('_').map((part, i) => (i === 0 ? part : part.charAt(0).toUpperCase() + part.slice(1))).join('');
+}

package/examples/mcp/types.ts

@@ -0,0 +1,34 @@
+/**
+ * types.ts — the shared shapes of the MCP reference registration: the
+ * structured tool result, the caller-facing deps, and the context handed to
+ * each tool group.
+ */
+import type { McpServer } from '@modelcontextprotocol/server';
+import type { AutotaskClient } from 'node-autotask';
+
+export type ToolReturn =
+  | { content: Array<{ type: 'text'; text: string }>; structuredContent: Record<string, unknown> }
+  | { content: Array<{ type: 'text'; text: string }>; isError: true };
+
+export interface CoreToolDeps {
+  /** null in DRY mode (no credentials — the client refuses to construct fail-closed). */
+  client: AutotaskClient | null;
+  /** True when no credentials are present: registry-backed tools validate + report, never issue. */
+  dry: boolean;
+  /**
+   * Issue #1: untrusted-content wrapping for helper-tool results. Default
+   * (absent): ON unless `AUTOTASK_UNTRUSTED_WRAP=off` — the explicit env
+   * switch (option beats env). Disabling logs a warning on stderr (the stdio
+   * protocol rides stdout; the tag name is fixed).
+   */
+  untrustedWrap?: boolean;
+}
+
+/** What each tool group (`registerXxxTools`) receives: the server plus the resolved deps. */
+export interface ToolContext {
+  server: McpServer;
+  client: AutotaskClient | null;
+  dry: boolean;
+  /** Resolved (option, then env) — never undefined here. */
+  untrustedWrap: boolean;
+}