iit-mcp-autotask 0.11.0 → 0.11.1

package/README.md

@@ -155,7 +155,13 @@ What the policy can and cannot do:
   original (the vendor ignores an update of `ticketID`): the new record gets a new id, create date and
   creator, and notifications may fire. A move into another company or contract always needs a signed
   approval grant; an unfinished earlier move of the same source blocks another until its ledger entry ages
-  out (14 days). Billed, attached, approved, closed-target and older-than-14-days sources are refused.
+  out (14 days) or a person clears it: in a terminal, as the server's OS user, with `AUTOTASK_STATE_DIR` set,
+  `autotask-mcp moves list` shows the blocked sources and `autotask-mcp moves resolve <resource>:<id>` (after you
+  checked both tickets in Autotask; you type the source id, and the copy's id when the ledger names one) closes the
+  ledger lines as `MOVE_RESOLVED` and audits it (`move_resolved`). It refuses within 10 minutes of the move being sent
+  (its engine may still be running) and, while the engine may still run, when the sending server is still registered or alive. A plan previewed
+  before the resolve cannot apply after it. It is not an
+  MCP tool; like the approvals CLI it is a guardrail, not a boundary against an agent with a same-user shell. Billed, attached, approved, closed-target and older-than-14-days sources are refused.
 - Hard rules no policy overrides: `authenticate.*` is never served; operations the SDK flags
   `requiresApproval`, and non-read sensitive ones (webhooks, `resources.transferOwnership`), always
   need approval; destructive and account-wide operations need it, and `allowUnattended` cannot waive

package/dist/main.js

@@ -12,6 +12,7 @@
 import { createMcpHandler } from '@modelcontextprotocol/server';
 import { ConfigError, loadConfig, serverCredentialDefaults } from './config.js';
 import { runApprovals } from './approvals.js';
+import { runMoves } from './moves.js';
 import { runDoctor } from './doctor.js';
 import { createLogger } from './logger.js';
 import { assertPlanHash } from './tools/catalog-data.js';
@@ -66,6 +67,8 @@ Usage: autotask-mcp [flags]
   approvals list|show|approve|reject <handle>
                             approvalMode external: a human decides a pending write (run it
                             yourself in a terminal; see the README); keygen <id> --ops <op,..|*>
+  moves list | resolve <resource>:<id>
+                            a human clears an unfinished move's MOVE_UNRESOLVED block (terminal only)
   --transport <stdio|http>  the transport (default: $MCP_TRANSPORT, else http)
   --host <address>          the http bind address (default: $MCP_HOST, else 127.0.0.1;
                             off loopback, AUTOTASK_HTTP_ALLOWED_HOSTS and AUTOTASK_HTTP_AUTH
@@ -125,6 +128,10 @@ function main() {
         process.exitCode = runApprovals(process.argv.slice(2), process.env, (t) => process.stdout.write(`${t}\n`));
         return;
     }
+    if (process.argv[2] === 'moves') {
+        process.exitCode = runMoves(process.argv.slice(2), process.env, (t) => process.stdout.write(`${t}\n`));
+        return;
+    }
     const args = parseCliArgs(process.argv.slice(2));
     // --version / --help predates the logger and the config: they print to stdout and exit 0.
     // (Safe on stdout: no stdio MCP session starts before this point.)

package/dist/moves.d.ts

@@ -0,0 +1,5 @@
+import { type Prompter } from './approvals.js';
+/** Run a `moves` subcommand; returns the process exit code. `argv` is everything after `autotask-mcp`. */
+export declare function runMoves(argv: string[], env: Record<string, string | undefined>, out: (t: string) => void, prompter?: () => Prompter & {
+    close(): void;
+}, now?: () => number): number;

package/dist/moves.js

@@ -0,0 +1,84 @@
+/**
+ * moves.ts — the `autotask-mcp moves` subcommands (issue #131): a person clears the MOVE_UNRESOLVED block on ONE move
+ * source after checking both tickets in Autotask. Run in a terminal as the server's OS user with AUTOTASK_STATE_DIR set.
+ *
+ * `list` only scans `ledger.jsonl` (it never opens the store: that registers a holder, rewrites the ledger and prunes).
+ * `resolve` shows the retained lines, takes the typed confirmation on /dev/tty, and ONLY THEN opens the store, calls
+ * `resolveMove` (ledger lines and the audit line under the op lock) and closes it: the blocking /dev/tty read must never
+ * sit between a lock and its heartbeat. It prints ids and codes only, never vendor text.
+ *
+ * Guardrail, not a boundary: an agent with a same-user shell can drive a pty or edit `ledger.jsonl` itself. Nothing on the
+ * MCP surface reaches this.
+ */
+import { userInfo } from 'node:os';
+import { join } from 'node:path';
+import { ApprovalsError, ttyPrompter } from './approvals.js';
+import { createLogger } from './logger.js';
+import { openStateStore, unresolvedMoves } from './write/store.js';
+const MOVES_USAGE = `usage: autotask-mcp moves list | moves resolve <time_entries|ticket_charges>:<id>
+Run it yourself, in a terminal, as the server's OS user, with AUTOTASK_STATE_DIR set to the value the server runs with.`;
+const SOURCE = /^(time_entries|ticket_charges):([1-9]\d{0,14})$/;
+const fail = (message) => {
+    throw new ApprovalsError(message);
+};
+const describe = (m, now) => `${m.targetKey}  ${m.state}${m.code !== undefined ? ` ${m.code}` : ''}  source ${m.sourceId ?? m.targetKey.split(':')[1]}${m.newId !== undefined ? `  new ${m.newId}` : ''}  sent ${Math.round((now - m.sentAt) / 60_000)} min ago`;
+/** Run a `moves` subcommand; returns the process exit code. `argv` is everything after `autotask-mcp`. */
+export function runMoves(argv, env, out, prompter = ttyPrompter, now = Date.now) {
+    try {
+        const [cmd, sub, source, ...extra] = argv;
+        if (cmd !== 'moves' || sub === undefined || extra.length > 0)
+            fail(MOVES_USAGE);
+        const dir = env.AUTOTASK_STATE_DIR;
+        if (dir === undefined)
+            fail('AUTOTASK_STATE_DIR must be set to the value the server runs with');
+        const ledgerPath = join(dir, 'ledger.jsonl');
+        if (sub === 'list') {
+            const rows = unresolvedMoves(ledgerPath);
+            out(rows.length === 0 ? 'No unfinished moves are retained.' : rows.map((m) => describe(m, now())).join('\n'));
+            return 0;
+        }
+        const m = sub === 'resolve' && source !== undefined ? SOURCE.exec(source) : null;
+        if (m === null)
+            fail(MOVES_USAGE);
+        const [resource, id] = [m[1], Number(m[2])];
+        const rows = unresolvedMoves(ledgerPath, `${resource}:${id}`);
+        if (rows.length === 0) {
+            out(`Nothing to resolve: no unfinished move of ${resource}:${id} is retained.`);
+            return 0;
+        }
+        const p = prompter();
+        try {
+            p.say(`Unfinished move(s) of ${resource}:${id}:\n${rows.map((r) => `  ${describe(r, now())}`).join('\n')}`);
+            p.say('Before resolving, check BOTH tickets in Autotask: the source may still exist, and a copy may exist on the target (a second move would make another). Resolving lets the agent move this source again.');
+            if (p.ask(`Type ${resource}:${id} to resolve it: `) !== `${resource}:${id}`)
+                fail('not resolved: the typed text did not match');
+            for (const newId of new Set(rows.flatMap((r) => (r.newId === undefined ? [] : [r.newId])))) {
+                if (p.ask(`The ledger names a copy, new id ${newId}. Look at it in Autotask, then type its id: `) !== String(newId))
+                    fail('not resolved: the typed copy id did not match');
+            }
+        }
+        finally {
+            p.close();
+        }
+        const store = openStateStore(dir, { log: createLogger('error'), now });
+        try {
+            const r = store.resolveMove(resource, id, userInfo().username, rows.map((x) => ({ idemKey: x.idemKey, state: x.state, ...(x.newId !== undefined ? { newId: x.newId } : {}) })), now());
+            if (!r.ok)
+                fail(`not resolved (${r.reason}): ${r.detail}`);
+            out(`Resolved ${resource}:${id} (${r.ok ? r.resolved : 0} ledger line(s) closed as MOVE_RESOLVED, audited). The agent may now move it again.`);
+        }
+        finally {
+            store.close();
+        }
+        return 0;
+    }
+    catch (err) {
+        if (err instanceof ApprovalsError) {
+            out(err.message);
+            return 1;
+        }
+        out(`error: ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+}
+//# sourceMappingURL=moves.js.map

package/dist/tools/context/client.d.ts

@@ -0,0 +1,23 @@
+import type { AutotaskConfig } from 'node-autotask';
+import type { Config } from '../../config.js';
+import type { Logger } from '../../logger.js';
+import type { ToolClient } from './types.js';
+/** The reserved placeholder origin (RFC 6761: nothing in the real world resolves it). */
+export declare const PLACEHOLDER_ORIGIN = "https://no-autotask-origin.invalid";
+export declare const PLACEHOLDER_BASE_URL = "https://no-autotask-origin.invalid/atservicesrest";
+/** Sentinel credential values a placeholder client is constructed with (never real, never dialled). */
+export declare const SENTINEL_CREDENTIAL = "unresolved-request-scope";
+/**
+ * The deployment-wide SDK options every client this factory builds gets (the agent profile +
+ * the env overrides + the cache preset + the literal-IP host floor + the audit sink).
+ * Precedence: explicit env > `agent` profile > SDK default (the profile fills only what is
+ * left unset).
+ */
+export declare function buildSdkBaseOptions(config: Config, log: Logger): Omit<AutotaskConfig, 'apiIntegrationCode' | 'userName' | 'secret'>;
+/** A fail-closed placeholder client: constructed but never dialled (context refuses pre-request). */
+export declare function buildPlaceholderClient(baseOptions: ReturnType<typeof buildSdkBaseOptions>): ToolClient;
+/** The one process-lifetime client of the stdio transport (the environment IS the identity). */
+export declare function buildStdioClient(config: Config, log: Logger): {
+    client: ToolClient;
+    origin: string;
+};

package/dist/tools/context/client.js

@@ -0,0 +1,96 @@
+/** SDK client construction: the base options, the placeholder client and the stdio client (issue #91). */
+import { AutotaskClient } from 'node-autotask';
+import { serverCredentialDefaults } from '../../config.js';
+import { normalizeBaseUrl } from '../../base-hosts.js';
+import { cacheOptionsForPreset } from '../catalog-data.js';
+// ---------------------------------------------------------------------------
+// SDK client construction
+// ---------------------------------------------------------------------------
+/** The reserved placeholder origin (RFC 6761: nothing in the real world resolves it). */
+export const PLACEHOLDER_ORIGIN = 'https://no-autotask-origin.invalid';
+export const PLACEHOLDER_BASE_URL = `${PLACEHOLDER_ORIGIN}/atservicesrest`;
+/** Sentinel credential values a placeholder client is constructed with (never real, never dialled). */
+export const SENTINEL_CREDENTIAL = 'unresolved-request-scope';
+/**
+ * The deployment-wide SDK options every client this factory builds gets (the agent profile +
+ * the env overrides + the cache preset + the literal-IP host floor + the audit sink).
+ * Precedence: explicit env > `agent` profile > SDK default (the profile fills only what is
+ * left unset).
+ */
+export function buildSdkBaseOptions(config, log) {
+    const defaultBase = config.AUTOTASK_BASE_URL;
+    const defaultBaseUrl = defaultBase === undefined ? undefined : normalizeBaseUrl(defaultBase)?.baseUrl;
+    return {
+        // The vendor budget guard: never the `library` defaults, never an operator-tuned value
+        // above the vendor cap (config validation enforces the cap).
+        profile: 'agent',
+        ...(config.AUTOTASK_RATE_LIMIT_PER_HOUR !== undefined ? { rateLimit: { perHour: config.AUTOTASK_RATE_LIMIT_PER_HOUR } } : {}),
+        ...(config.AUTOTASK_MAX_CONCURRENT !== undefined ? { maxConcurrent: config.AUTOTASK_MAX_CONCURRENT } : {}),
+        ...(config.AUTOTASK_TIMEOUT_MS !== undefined ? { timeoutMs: config.AUTOTASK_TIMEOUT_MS } : {}),
+        ...(config.AUTOTASK_MAX_RETRIES !== undefined ? { maxRetries: config.AUTOTASK_MAX_RETRIES } : {}),
+        // The literal-IP SSRF floor: a LITERAL private/loopback origin is refused at construction
+        // even if the deployment allow-list named it (the private bound wins — security S2/C2.4).
+        hostPolicy: {
+            blockPrivateHosts: true,
+            ...(defaultBaseUrl !== undefined ? { allowedOrigins: [defaultBaseUrl] } : {}),
+        },
+        // The SCOPING Stage-4 cache deviation (user-approved): `on` sends no cache blocks (the SDK
+        // default-on caches) UNLESS the AUTOTASK_FIELD_CACHE_TTL_MS override is set — then the
+        // scalar fieldCache block rides (the TTL pass-through); `off` opts every channel out
+        // explicitly (every read re-dials the vendor) and is never touched by the override.
+        ...cacheOptionsForPreset(config.AUTOTASK_CACHE_PRESET, config.AUTOTASK_FIELD_CACHE_TTL_MS),
+        // One bounded line per settled request (the SDK stamps the correlation id and redacts the
+        // body at the wire; the `path` carries no query values by construction). Only the event's
+        // own shape metadata is forwarded — never bodies or payload values (security S9).
+        onAudit: (event) => {
+            const e = event;
+            log.info('autotask request', {
+                ...(typeof e.correlationId === 'string' ? { correlationId: e.correlationId } : {}),
+                ...(typeof e.operation === 'string' ? { operation: e.operation } : {}),
+                ...(typeof e.method === 'string' ? { method: e.method } : {}),
+                ...(typeof e.path === 'string' ? { path: e.path } : {}),
+                ...(typeof e.status === 'number' ? { status: e.status } : {}),
+                ...(typeof e.durationMs === 'number' ? { durationMs: e.durationMs } : {}),
+                ...(typeof e.errorCode === 'string' ? { errorCode: e.errorCode } : {}),
+                ...(e.notSent === true ? { notSent: true } : {}),
+            });
+        },
+    };
+}
+/** A fail-closed placeholder client: constructed but never dialled (context refuses pre-request). */
+export function buildPlaceholderClient(baseOptions) {
+    // The placeholders keep the literal-IP floor only: their reserved origin must survive
+    // construction so the sentinel is what a dialled placeholder would present, unmistakably.
+    const client = new AutotaskClient({
+        ...baseOptions,
+        apiIntegrationCode: SENTINEL_CREDENTIAL,
+        userName: SENTINEL_CREDENTIAL,
+        secret: SENTINEL_CREDENTIAL,
+        baseUrl: PLACEHOLDER_BASE_URL,
+        hostPolicy: { blockPrivateHosts: true },
+    });
+    return client;
+}
+/** The one process-lifetime client of the stdio transport (the environment IS the identity). */
+export function buildStdioClient(config, log) {
+    const baseOptions = buildSdkBaseOptions(config, log);
+    const defaults = serverCredentialDefaults(config);
+    if (defaults === undefined || config.AUTOTASK_BASE_URL === undefined) {
+        // Unreachable: loadConfig requires all four under stdio. The line after it is unreachable;
+        // it exists so the narrowing is a type fact rather than a comment.
+        throw new Error('stdio client built without a complete credential tuple — loadConfig guarantees this cannot happen');
+    }
+    const normalized = normalizeBaseUrl(config.AUTOTASK_BASE_URL);
+    if (normalized === undefined)
+        throw new Error('AUTOTASK_BASE_URL failed normalization after boot validation — this cannot happen');
+    const client = new AutotaskClient({
+        ...baseOptions,
+        apiIntegrationCode: defaults.apiIntegrationCode,
+        userName: defaults.userName,
+        secret: defaults.secret,
+        ...(defaults.impersonationResourceId !== undefined ? { impersonationResourceId: defaults.impersonationResourceId } : {}),
+        baseUrl: normalized.baseUrl,
+    });
+    return { client, origin: normalized.origin };
+}
+//# sourceMappingURL=client.js.map

package/dist/tools/context/derive.d.ts

@@ -0,0 +1,9 @@
+import type { ToolDeps, ToolContext } from './types.js';
+/** Derive the context the registrations share. */
+export declare function deriveToolContext(deps: ToolDeps, served?: ReadonlySet<string>): ToolContext;
+/**
+ * A vendor 401 (or impersonation-scope 401/403) deletes the pooled entry so a stale identity is
+ * not negative-cached and replayed (security S1/C1.8, S3/C3.5): the next request with the same
+ * tuple recreates the client and starts fresh. Safe to call with a non-pooled client (no-op).
+ */
+export declare function releaseClientOnError(deps: ToolDeps, err: unknown): void;

package/dist/tools/context/derive.js

@@ -0,0 +1,36 @@
+/** Deriving a tool context from the deps, and releasing a client on error (issue #91). */
+import { isAutotaskError } from 'node-autotask';
+import { recordById, toolDescription, untrustedFieldsOf } from '../catalog-data.js';
+/** Derive the context the registrations share. */
+export function deriveToolContext(deps, served = new Set()) {
+    return {
+        ...deps,
+        served,
+        writable: new Set(deps.write === undefined ? [] : Object.keys(deps.write.runtime.loaded.policy.ops)),
+        record: recordById,
+        untrustedFields: (operation) => {
+            const rec = recordById(operation);
+            return rec === undefined ? [] : untrustedFieldsOf(rec);
+        },
+        description: toolDescription,
+    };
+}
+/**
+ * A vendor 401 (or impersonation-scope 401/403) deletes the pooled entry so a stale identity is
+ * not negative-cached and replayed (security S1/C1.8, S3/C3.5): the next request with the same
+ * tuple recreates the client and starts fresh. Safe to call with a non-pooled client (no-op).
+ */
+export function releaseClientOnError(deps, err) {
+    if (deps.pool === undefined || deps.poolConfig === undefined)
+        return;
+    const code = err?.code;
+    const name = err?.name;
+    if (isAutotaskError(err) &&
+        ((code === 'UNAUTHORIZED' || code === 'FORBIDDEN') ||
+            name === 'UnauthorizedError' ||
+            name === 'ForbiddenError')) {
+        const removed = deps.pool.delete(deps.poolConfig);
+        deps.log.info('deleted pooled client after credential refusal', { removed, poolSize: deps.pool.size });
+    }
+}
+//# sourceMappingURL=derive.js.map

package/dist/tools/context/ops.d.ts

@@ -0,0 +1,29 @@
+import type { ToolClient, QueryWalkParams, QueryWalkResult, ToolOps } from './types.js';
+/** The real SDK bindings (the production default; tests substitute a fixture-backed bundle). */
+/**
+ * The SDK operations bundle (the production default; tests substitute a fixture-backed bundle).
+ *
+ * (Historical, FT-4: before node-autotask 0.9.0 the invoke router resolved `client['authenticate']` to the
+ * convenience METHOD, so `authenticate.get` answered CONFIG_ERROR and this bundle special-cased it to
+ * `authenticateResource.get()`. 0.9.0 routes it to the resource holder (#88), so every read now goes through
+ * `invokeRead` and its governor; `authenticate.*` is refused by the deployment policy before it.)
+ */
+export declare const defaultToolOps: ToolOps;
+/**
+ * Walk one `*.query` operation with the resource's OWN iterator (`client[<resource>].query(...)` —
+ * the public AsyncIterable over the SDK's internal page fetcher; see {@link ToolOps.queryWalk}).
+ * The page size is the vendor maximum (500) and `maxRows` caps the TOTAL rows.
+ *
+ * Truncation honesty: the iterator is advanced ONE record past the cap purely to learn whether more
+ * records exist; that record is DISCARDED, so a data set of exactly `maxRows` rows reports
+ * `truncated: false` and the page count is untouched.
+ */
+export declare function walkQuery(client: ToolClient, operation: string, params: QueryWalkParams, maxRows: number): Promise<QueryWalkResult>;
+/**
+ * Propagate the MCP request's cancellation into the SDK's in-flight request (architecture 7.6:
+ * an abandoned request stops consuming vendor budget). The SDK's `withSignal` returns
+ * `undefined` when the signal has already aborted or no transport is attached — the SDK's own
+ * handler then answers the typed cancellation; the handler's generic catch would otherwise
+ * re-report it as a tool error, so this wrapper throws the SDK's typed `AbortError` instead.
+ */
+export declare function withSignal(client: ToolClient, signal: AbortSignal | undefined, fn: () => Promise<unknown>): Promise<unknown>;

package/dist/tools/context/ops.js

@@ -0,0 +1,70 @@
+/** The default tool ops: the bounded query walk and the abort-signal wrapper (issue #91). */
+import { AutotaskClient, camelKey } from 'node-autotask';
+import { AutotaskConfigError } from 'node-autotask';
+import { fetchByIds, fetchMany, invokeDelete, invokeRead, invokeWrite, relationshipMap, resolveAny, searchAcrossResources } from 'node-autotask/operations';
+/** The real SDK bindings (the production default; tests substitute a fixture-backed bundle). */
+/**
+ * The SDK operations bundle (the production default; tests substitute a fixture-backed bundle).
+ *
+ * (Historical, FT-4: before node-autotask 0.9.0 the invoke router resolved `client['authenticate']` to the
+ * convenience METHOD, so `authenticate.get` answered CONFIG_ERROR and this bundle special-cased it to
+ * `authenticateResource.get()`. 0.9.0 routes it to the resource holder (#88), so every read now goes through
+ * `invokeRead` and its governor; `authenticate.*` is refused by the deployment policy before it.)
+ */
+export const defaultToolOps = {
+    invokeRead: (client, operation, args, opts, signal) => withSignal(client, signal, () => invokeRead(client, operation, args, opts ?? {})),
+    invokeWrite: (client, operation, args, opts, signal) => withSignal(client, signal, () => invokeWrite(client, operation, args, opts ?? {})),
+    invokeDelete: (client, operation, args, opts, signal) => withSignal(client, signal, () => invokeDelete(client, operation, args, opts ?? {})),
+    resolveAny: (client, identifier, opts, signal) => withSignal(client, signal, () => resolveAny(client, identifier, opts ?? {})),
+    searchAcrossResources: (client, query, opts, signal) => withSignal(client, signal, () => searchAcrossResources(client, query, opts ?? {})),
+    fetchMany: (client, items, opts, signal) => withSignal(client, signal, () => fetchMany(client, items, opts ?? {})),
+    fetchByIds: (client, items, opts, signal) => withSignal(client, signal, () => fetchByIds(client, items, opts ?? {})),
+    relationshipMap: (client, resourceKey) => relationshipMap(client, resourceKey),
+    hourlyBudget: (client) => Promise.resolve(client.hourlyBudget()),
+    queryWalk: (client, operation, params, maxRows, signal) => withSignal(client, signal, () => walkQuery(client, operation, params, maxRows)),
+    freshen: (client) => client.http.readCache?.clear(),
+};
+/**
+ * Walk one `*.query` operation with the resource's OWN iterator (`client[<resource>].query(...)` —
+ * the public AsyncIterable over the SDK's internal page fetcher; see {@link ToolOps.queryWalk}).
+ * The page size is the vendor maximum (500) and `maxRows` caps the TOTAL rows.
+ *
+ * Truncation honesty: the iterator is advanced ONE record past the cap purely to learn whether more
+ * records exist; that record is DISCARDED, so a data set of exactly `maxRows` rows reports
+ * `truncated: false` and the page count is untouched.
+ */
+export async function walkQuery(client, operation, params, maxRows) {
+    const resourceKey = operation.slice(0, operation.indexOf('.'));
+    const holder = client[camelKey(resourceKey)];
+    if (holder === undefined || typeof holder.query !== 'function') {
+        throw new AutotaskConfigError(`output_path: the client exposes no query iterator for "${resourceKey}" (operation ${operation}) — nothing was written`, { operation });
+    }
+    const bag = { maxRecords: 500 };
+    if (params.filter !== undefined)
+        bag.filter = params.filter;
+    if (params.includeFields !== undefined)
+        bag.includeFields = params.includeFields;
+    if (params.via !== undefined)
+        bag.via = params.via;
+    const items = [];
+    for await (const item of holder.query(bag)) {
+        if (items.length >= maxRows)
+            return { items, truncated: true };
+        items.push(item);
+    }
+    return { items, truncated: false };
+}
+/**
+ * Propagate the MCP request's cancellation into the SDK's in-flight request (architecture 7.6:
+ * an abandoned request stops consuming vendor budget). The SDK's `withSignal` returns
+ * `undefined` when the signal has already aborted or no transport is attached — the SDK's own
+ * handler then answers the typed cancellation; the handler's generic catch would otherwise
+ * re-report it as a tool error, so this wrapper throws the SDK's typed `AbortError` instead.
+ */
+export function withSignal(client, signal, fn) {
+    const c = client;
+    if (signal === undefined || typeof c.withSignal !== 'function')
+        return fn();
+    return c.withSignal(signal, fn);
+}
+//# sourceMappingURL=ops.js.map

package/dist/tools/context/pool.d.ts

@@ -0,0 +1,5 @@
+/** The per-tenant client pool (issue #91). */
+import { type ClientPool } from 'node-autotask/pool';
+import type { Logger } from '../../logger.js';
+/** The process-lifetime bounded pool of the http transport (security D-1, ratified). */
+export declare function createTenantPool(log: Logger): ClientPool;

package/dist/tools/context/pool.js

@@ -0,0 +1,9 @@
+/** The per-tenant client pool (issue #91). */
+import { createClientPool } from 'node-autotask/pool';
+/** The process-lifetime bounded pool of the http transport (security D-1, ratified). */
+export function createTenantPool(log) {
+    const pool = createClientPool({ maxSize: 128 });
+    log.info('tenant client pool ready', { maxSize: 128 });
+    return pool;
+}
+//# sourceMappingURL=pool.js.map

package/dist/tools/context/scope.d.ts

@@ -0,0 +1,24 @@
+/** HTTP per-request credential and scope resolution (issue #91). */
+import type { ClientPool } from 'node-autotask/pool';
+import type { Config } from '../../config.js';
+import type { Logger } from '../../logger.js';
+import type { HttpScopeResolver } from './types.js';
+import { buildSdkBaseOptions } from './client.js';
+/**
+ * Build the per-request scope resolver for the http transport.
+ *
+ * The effective policy (mirrors the security S2/C2.2 layering):
+ * - a caller-named origin is refused unless `AUTOTASK_ALLOWED_BASE_HOSTS` permits it;
+ * - allow-list unset + default origin set -> the default origin only is accepted;
+ * - neither set -> boot is refused unless the explicit lab-only `AUTOTASK_ALLOW_ANY_BASE_HOST`
+ *   (config validation makes that mode reachable by typing it out, never by forgetting);
+ * - the default origin is operator truth: never checked against the allow-list, but it must
+ *   itself pass the https + private-IP bounds (enforced at boot / at construction).
+ *
+ * Credentials are all-or-nothing: a request presenting 1 or 2 of the three identity headers is
+ * malformed and resolves to the `partial_credential` refusal (there is no per-field default
+ * fill); a request presenting none uses the server-held default tuple ONLY when it is set AND
+ * the request did not name a different origin (the default identity is only ever presented to
+ * the default origin — a caller cannot aim it at a host it controls).
+ */
+export declare function createHttpScopeResolver(config: Config, log: Logger, pool: ClientPool, baseOptions: ReturnType<typeof buildSdkBaseOptions>): HttpScopeResolver;

package/dist/tools/context/scope.js

@@ -0,0 +1,165 @@
+import { serverCredentialDefaults } from '../../config.js';
+import { baseHostAllowed, normalizeBaseUrl } from '../../base-hosts.js';
+import { CREDENTIAL_LOAD_HINT, detectCredentialShape } from '../../credential.js';
+import { buildSdkBaseOptions, buildPlaceholderClient } from './client.js';
+/**
+ * Build the per-request scope resolver for the http transport.
+ *
+ * The effective policy (mirrors the security S2/C2.2 layering):
+ * - a caller-named origin is refused unless `AUTOTASK_ALLOWED_BASE_HOSTS` permits it;
+ * - allow-list unset + default origin set -> the default origin only is accepted;
+ * - neither set -> boot is refused unless the explicit lab-only `AUTOTASK_ALLOW_ANY_BASE_HOST`
+ *   (config validation makes that mode reachable by typing it out, never by forgetting);
+ * - the default origin is operator truth: never checked against the allow-list, but it must
+ *   itself pass the https + private-IP bounds (enforced at boot / at construction).
+ *
+ * Credentials are all-or-nothing: a request presenting 1 or 2 of the three identity headers is
+ * malformed and resolves to the `partial_credential` refusal (there is no per-field default
+ * fill); a request presenting none uses the server-held default tuple ONLY when it is set AND
+ * the request did not name a different origin (the default identity is only ever presented to
+ * the default origin — a caller cannot aim it at a host it controls).
+ */
+export function createHttpScopeResolver(config, log, pool, baseOptions) {
+    const defaultBase = config.AUTOTASK_BASE_URL;
+    const defaultNormalized = defaultBase === undefined ? undefined : normalizeBaseUrl(defaultBase);
+    const defaultOrigin = defaultNormalized?.origin;
+    const placeholders = {
+        no_credential: buildPlaceholderClient(baseOptions),
+        partial_credential: buildPlaceholderClient(baseOptions),
+        no_origin: buildPlaceholderClient(baseOptions),
+        bad_origin: buildPlaceholderClient(baseOptions),
+        origin_not_allowed: buildPlaceholderClient(baseOptions),
+        // Unused: the malformed path builds its placeholder lazily (the strategy name carries the
+        // anomaly names, so there is one placeholder per anomaly set, not one for the kind).
+        malformed_credential: buildPlaceholderClient(baseOptions),
+    };
+    /**
+     * The malformed-credential placeholders (issue #4b): one per anomaly SET, built lazily and cached,
+     * because the strategy name carries the anomaly names and the anomaly vocabulary is small and
+     * bounded — a fresh client per malformed request would let a caller allocate one per request. The
+     * refusal itself is decided by `tools/results.ts` from the anomaly names in the strategy name.
+     */
+    const malformedPlaceholders = new Map();
+    /**
+     * The pre-dispatch credential shape gate, on the values THIS request will present.
+     *
+     * It runs before any client is constructed (so before any dial, and before the origin checks —
+     * a malformed credential is refused whatever origin it named). Both the per-request headers and
+     * the server-held defaults win the same treatment: whichever value would be presented is the one
+     * judged.
+     */
+    function refuseMalformedCredentials(values) {
+        const anomalies = new Set();
+        for (const [, value] of values) {
+            if (value === undefined || value.trim() === '')
+                continue;
+            for (const anomaly of detectCredentialShape(value))
+                anomalies.add(anomaly);
+        }
+        if (anomalies.size === 0)
+            return undefined;
+        const list = [...anomalies];
+        log.warn('refused a malformed Autotask credential before dialing', {
+            source: 'request headers (or the server-held defaults)',
+            anomalies: list,
+            hint: CREDENTIAL_LOAD_HINT,
+        });
+        const id = list.join(',');
+        let client = malformedPlaceholders.get(id);
+        if (client === undefined) {
+            client = { __malformedAnomalies: list };
+            malformedPlaceholders.set(id, client);
+        }
+        return { client, refusal: { kind: 'malformed_credential', anomalies: list } };
+    }
+    return {
+        resolve(scope) {
+            // ---- origin ----
+            const headerBase = scope.baseUrl;
+            const headerNormalized = headerBase === undefined ? undefined : normalizeBaseUrl(headerBase);
+            const callerNamed = headerBase !== undefined && (headerNormalized === undefined || headerNormalized.origin !== defaultOrigin);
+            const base = headerBase ?? defaultBase;
+            const baseNormalized = base === undefined ? undefined : (headerBase !== undefined ? headerNormalized : defaultNormalized);
+            // ---- pre-dispatch credential SHAPE gate (issue #4b) ----
+            // Runs first: a malformed value is refused before any client is constructed and before the
+            // origin policy is consulted, because the shape is decidable without a dial and a malformed
+            // credential is refused whatever origin it named. Both sources are judged: the request's own
+            // headers, and the server-held defaults a header-less request would run as.
+            const defaultsForShape = serverCredentialDefaults(config);
+            const malformed = refuseMalformedCredentials([
+                ['X-Autotask-Api-Integration-Code', scope.apiIntegrationCode ?? defaultsForShape?.apiIntegrationCode],
+                ['X-Autotask-UserName', scope.userName ?? defaultsForShape?.userName],
+                ['X-Autotask-Secret', scope.secret ?? defaultsForShape?.secret],
+                ['X-Autotask-Impersonation-Resource-Id', scope.impersonationResourceId ?? defaultsForShape?.impersonationResourceId],
+            ]);
+            if (malformed !== undefined)
+                return malformed;
+            // ---- credentials (all-or-nothing) ----
+            const present = [scope.apiIntegrationCode, scope.userName, scope.secret].filter((v) => v !== undefined).length;
+            let creds;
+            if (present === 3) {
+                creds = {
+                    apiIntegrationCode: scope.apiIntegrationCode,
+                    userName: scope.userName,
+                    secret: scope.secret,
+                    ...(scope.impersonationResourceId !== undefined ? { impersonationResourceId: scope.impersonationResourceId } : {}),
+                };
+            }
+            else if (present > 0) {
+                // A partial tuple is malformed: fail closed, no default fill.
+                log.warn('request refused: partial credential tuple', { presented: present });
+                return { client: placeholders.partial_credential, refusal: { kind: 'partial_credential' } };
+            }
+            else {
+                const defaults = serverCredentialDefaults(config);
+                // The default identity is only ever presented to the DEFAULT origin.
+                if (defaults !== undefined && !callerNamed) {
+                    creds = defaults;
+                }
+            }
+            // ---- refusals, in precedence order ----
+            if (creds === undefined) {
+                return { client: placeholders.no_credential, refusal: { kind: 'no_credential' } };
+            }
+            if (base === undefined || baseNormalized === undefined) {
+                const kind = headerBase !== undefined && headerNormalized === undefined ? 'bad_origin' : 'no_origin';
+                return { client: placeholders[kind], refusal: { kind } };
+            }
+            if (callerNamed) {
+                const allowed = config.AUTOTASK_ALLOWED_BASE_HOSTS === undefined
+                    ? config.AUTOTASK_ALLOW_ANY_BASE_HOST // unset list + no default origin: only the explicit lab opt-in admits
+                    : baseHostAllowed(headerBase, config.AUTOTASK_ALLOWED_BASE_HOSTS);
+                if (!allowed) {
+                    // The name of the policy is the only diagnostic: the refused value is never echoed.
+                    log.warn('request refused: caller-named origin not allowed', { allowAny: config.AUTOTASK_ALLOW_ANY_BASE_HOST, impersonated: creds.impersonationResourceId !== undefined });
+                    return { client: placeholders.origin_not_allowed, refusal: { kind: 'origin_not_allowed' } };
+                }
+            }
+            // ---- the pooled tenant client (D-1: the single sanctioned in-process state) ----
+            // Security S2/C2.2 layering (FT-1): the server allow-list is what ADMITS the caller
+            // origin; the SDK hostPolicy adds only the literal-IP floor. The client's allowedOrigins
+            // must therefore cover every origin the server admits for THIS request — the caller's own
+            // (allow-listed) origin plus the deployment default when set. Deriving it from the
+            // deployment-wide default alone 500'd an allow-listed NON-default caller origin at client
+            // construction (HostPolicyDeniedError out of the per-request factory).
+            const allowedOrigins = [baseNormalized.origin];
+            if (defaultOrigin !== undefined && defaultOrigin !== baseNormalized.origin)
+                allowedOrigins.push(defaultOrigin);
+            const poolConfig = {
+                apiIntegrationCode: creds.apiIntegrationCode,
+                userName: creds.userName,
+                secret: creds.secret,
+                ...(creds.impersonationResourceId !== undefined ? { impersonationResourceId: creds.impersonationResourceId } : {}),
+                baseUrl: baseNormalized.baseUrl,
+                ...baseOptions,
+                hostPolicy: {
+                    ...(baseOptions.hostPolicy ?? {}),
+                    allowedOrigins,
+                },
+            };
+            const client = pool.get(poolConfig);
+            return { client, origin: baseNormalized.origin, poolConfig };
+        },
+    };
+}
+//# sourceMappingURL=scope.js.map