iit-mcp-autotask 0.38.8 → 0.40.0

package/.env.example

@@ -52,13 +52,11 @@ MCP_TRANSPORT=stdio
 # readonly (default): reads only, no state. operator: adds autotask_write (preview) and
 # autotask_apply (execute the previewed plan), governed by AUTOTASK_WRITE; needs the state dir and run scope below.
 AUTOTASK_PROFILE=readonly
-# operator: which writes are served: allow, gate (a person confirms) or deny per operation; unlisted is read-only.
-# Grammar, dedup, limits and trusted host prompts: docs/write-gate.md.
-# AUTOTASK_WRITE=*:gate,tickets.*:allow,time_entries.create:allow,companies.update:deny
+# operator: which writes are served: allow or deny per operation; unlisted is denied.
+# Hard rules require human confirmation. Grammar and dedup: docs/write-gate.md.
+# AUTOTASK_WRITE=*:deny,tickets.*:allow,time_entries.create:allow,companies.update:deny
 # AUTOTASK_DEDUP=companies.create:companyName
-# AUTOTASK_WRITE_LIMITS=50/h,200/d
-# AUTOTASK_TRUSTED_HOST_PROMPT=stdio
-# operator: the state dir (mode 0700; plans, ledger, audit log, lock; one process per dir).
+# operator: the state dir (mode 0700; plans, ledger, audit, locks; same-version processes on one host may share it).
 # AUTOTASK_STATE_DIR=/var/lib/autotask-mcp
 # operator on stdio: the run scope (required), {"companyIds":[...]} or {"all":true} (any
 # company). On HTTP set runScope per token instead.
@@ -68,7 +66,7 @@ AUTOTASK_PROFILE=readonly
 # The kill file: while it exists every preview and apply is denied (default <state dir>/KILL).
 # AUTOTASK_KILL_FILE=/var/lib/autotask-mcp/KILL
 # Optional toolsets on top of core (core is always on): a comma list of service, records, finance,
-# or all. An unknown name fails boot. Unset = core only (12 tools).
+# or all. An unknown name fails boot. Unset = core only.
 # AUTOTASK_TOOLSETS=service,records,finance
 # IANA time zone of the people asking (their local "today"), default UTC; not the tenant's or
 # the server's zone. Autotask stores UTC; the zone is reported by
@@ -81,10 +79,11 @@ AUTOTASK_PROFILE=readonly
 # AUTOTASK_SECRET_READS. authenticate.* (a credential-minting read) is always refused.
 
 # --- Per-tenant read cache (in-process; never cross-tenant; never on disk) ---
-# on (default): each pooled tenant client applies the SDK reference TTL table (structural ~1 h /
-# mutable ~5 min / base ~1 min) plus the field-metadata cache; repeated reads of the same record
-# are served from the tenant's cache until TTL expiry. off: every read re-dials the vendor.
-AUTOTASK_CACHE_PRESET=on
+# on (default): the SDK's default-on caches apply to each pooled tenant client (read ~5 min,
+# reference tables ~1 h, field metadata ~5 min); repeated reads of the same record are served
+# from the tenant's cache until TTL expiry. off: `cache: false` is sent — every read re-dials
+# the vendor.
+AUTOTASK_CACHE=on
 
 # --- Vendor budget (the server boots the SDK in the conservative `agent` profile; overrides here) ---
 # AUTOTASK_RATE_LIMIT_PER_HOUR=8000

package/README.md

@@ -11,7 +11,7 @@ client + SDK-owned TTL caches).
 ## Tool surface
 
 The **core** toolset (10 tools) is always served; `AUTOTASK_TOOLSETS` adds `service`, `records` and
-`finance` (or `all`, 17 tools); the operator profile adds two. The whole tool surface (19 tools) is
+`finance` (or `all`, 18 tools); the operator profile adds two. The whole tool surface (20 tools) is
 listed below. Every other operation in the SDK's operation registry stays
 reachable through the generic layer: `autotask_catalog` finds the key, `autotask_describe` serves
 its contract (slim by default: transport and retry detail dropped, long text cut, the first two
@@ -22,7 +22,7 @@ examples; `full: true` serves the complete record, `summary: true` about 2 KB),
 | core (always) | `autotask_guide` · `autotask_catalog` · `autotask_describe` · `autotask_read` · `autotask_resolve` · `autotask_query` · `autotask_tenant_status` · `autotask_ticket_full_context` · `autotask_company_full_profile` · `autotask_resource_workload` |
 | `service` | `autotask_project_get_context` · `autotask_service_call_full_profile` |
 | `records` | `autotask_contact_full_profile` · `autotask_configuration_item_profile` · `autotask_contract_full_profile` |
-| `finance` | `autotask_quote_get` · `autotask_invoice_get` (`format`: `record`, `html`, `xml`, `pdf`) |
+| `finance` | `autotask_quote_get` · `autotask_invoice_get` (`format`: `record`, `html`, `xml`, `pdf`) · `autotask_revenue_rollup` |
 | `operator` (operator profile) | `autotask_write` (preview, changes nothing) · `autotask_apply` (execute the previewed plan) |
 
 - `autotask_resolve` turns any identifier into a record: an id or name, `by: "ticket_number"`,
@@ -81,7 +81,7 @@ vendor, so loading a playbook costs no wire and adds no injection surface.
 - `{skill, section}`: one of its `## ` sections.
 
 Skills: `ticket-triage`, `company-360`, `unbilled-work-review`, `contract-profitability`,
-`invoice-export`, `filter-semantics`, `slim-reads`, and on the operator profile `log-time-entry` and `crm-management`.
+`revenue-rollup`, `invoice-export`, `filter-semantics`, `slim-reads`, and on the operator profile `log-time-entry` and `crm-management`.
 
 The playbooks are discoverable in both directions:
 
@@ -100,6 +100,7 @@ part miss never fails the call (typed `absent`); only a missing root record fail
 { status: ok|needs_input|ambiguous|denied|error,
   data, next: proceed|supply_input|choose_candidate|...|retry|stop,
   reasons: [{ code, field?, detail }], retryable, correlationId, summary }
+// status ok omits next, reasons, retryable and correlationId
 ```
 
 `isError` is set exactly for `denied` and `error`; on an error `data` is the typed error payload
@@ -143,7 +144,7 @@ warning naming any unrecognised `AUTOTASK_*` variable at boot), so the profile g
 
 ### Operator profile (writes)
 
-Writes are two calls. `autotask_write {operation, args, reason?, idempotency_key?}` previews: it
+Writes are two calls. `autotask_write {operation, args, reason?}` previews: it
 reads the target live, runs the SDK dry run, evaluates the policy and returns a decision, a diff and,
 when allowed, a plan handle (`pln_...`, valid 15 minutes). Nothing is written. `autotask_apply
 {plan}` executes exactly that plan, after checking that nothing it depends on has changed. Targets
@@ -155,44 +156,28 @@ An operator deployment needs:
 | Variable | Meaning |
 |----------|---------|
 | `AUTOTASK_PROFILE=operator` (or an operator token) | the profile |
-| `AUTOTASK_WRITE` | which writes are served and how: `allow`, `gate` or `deny` per operation, unlisted is read-only (grammar in [docs/write-gate.md](docs/write-gate.md)) |
-| `AUTOTASK_STATE_DIR` | mode 0700; holds encrypted plans, the idempotency ledger, the hash-chained audit log, the primary lock and the holder registry (many processes may share one dir — see below) |
+| `AUTOTASK_WRITE` | which writes are served and how: `allow` or `deny` per operation, unlisted is read-only (grammar in [docs/write-gate.md](docs/write-gate.md)) |
+| `AUTOTASK_STATE_DIR` | mode 0700; holds encrypted plans, the idempotency ledger, the append-only JSONL audit log, the primary lock and the holder registry (many processes may share one dir — see below) |
 | `AUTOTASK_RUN_SCOPE` | `{"companyIds":[...]}` or `{"all":true}`: the run scope on stdio and in gateway mode (one scope shared by every gateway principal). In tokens mode each operator token carries `runScope` instead |
 | `AUTOTASK_PRINCIPAL` | stdio: the name plans and the audit log are bound to (default `stdio`) |
 | `AUTOTASK_KILL_FILE` | optional: while this file exists every preview and apply is denied (default `<state dir>/KILL`) |
 
 What the write access can and cannot do (full reference: [docs/write-gate.md](docs/write-gate.md)):
 
-- `AUTOTASK_WRITE` lists operations, families (`tickets.*`) or `*`, each `allow` (applies without a
-  person), `gate` (a person confirms the apply) or `deny`. An operation not listed is `OP_NOT_ALLOWED`.
-  `AUTOTASK_DEDUP` names the duplicate-check fields for a create, `AUTOTASK_WRITE_LIMITS` caps writes
-  (`50/h,200/d`) and `AUTOTASK_TRUSTED_HOST_PROMPT` names the clients whose own permission prompt counts
-  as the confirmation. A bad entry fails boot.
-- A gated apply is confirmed by a trusted host's own prompt, else by one confirm form (MCP elicitation);
-  a client that can do neither gets `GATE_UNSUPPORTED`, and a decline or dismissal `GATE_DECLINED`.
-  Nothing is sent in either case.
-- Moving a time entry or ticket charge to another ticket (#107): `time_entries.moveToTicket` and
-  `ticket_charges.moveToTicket`. Preview `autotask_write {operation, args: [sourceId, toTicketId]}`, then
-  apply. The server creates the copy on the target ticket, verifies it and deletes the 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 is always gated. An unfinished earlier
-  move of the same source blocks another until its ledger entry ages 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
-  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, and 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 setting overrides: `authenticate.*` is never served; operations the SDK flags
-  `requiresApproval` or sensitive (webhooks, `resources.transferOwnership`, `contacts.moveToCompany`, deletes) can only
-  be `gate` or `deny`. An exact `allow` entry for one is a boot error; a family or `*` entry resolves it
-  to `gate`. Destructive and move operations can be `allow`ed (see the trust model in the doc).
-- When a person must finish a job by hand (a move whose source delete the vendor refused), the result is
-  `next: manual_action` and `data.move.manualAction` carries what to do and, when the pinned SDK
-  provides `operations.uiLink`, a clickable Autotask deep link. There is no `autotask_delete` (D-12):
-  deletes preview through `autotask_write`.
+- `AUTOTASK_WRITE` lists operations, families (`tickets.*`) or `*`, each `allow` or `deny`.
+  Unlisted writes are `OP_NOT_ALLOWED`. `AUTOTASK_DEDUP` names duplicate-check fields for creates.
+  A bad entry fails boot; the former `gate` mode is refused.
+- Hard rules still require a person for SDK `requiresApproval` or sensitive operations, and moves
+  across companies or contracts. The server asks through MCP form elicitation; a client without
+  form support gets `GATE_UNSUPPORTED`, and decline or dismissal gives `GATE_DECLINED`.
+  A gateway client id or host permission prompt never bypasses this check.
+- Move a time entry or ticket charge with `time_entries.moveToTicket` or `ticket_charges.moveToTicket`,
+  args `[sourceId, toTicketId]`. The SDK copies, verifies, then deletes the source; the new record
+  gets a new id and history, and notifications may fire. Billed, attached, approved, closed-target
+  and old sources are refused by the SDK. Follow `data.move.manualAction` when a person must delete
+  the source. A partial or unknown move is never blindly retried: check both tickets in Autotask.
+  The server retains write-ahead/replay protection, but no separate move recovery snapshot or
+  `moves list/resolve` command. Deletes preview through `autotask_write`.
 - The company scope is read from the live records the write touches (the target, its parent, the
   ticket, project, task or contract it references, and any `companyID` it sets), never from names
   or titles. A reference that cannot be read is refused.
@@ -205,19 +190,24 @@ the preview diff shows exactly what is sent. A string that still carries a combi
 precomposed form after NFC (for example a lone U+0301) is refused `INPUT_INVALID`: send the
 precomposed character.
 
-Outcomes the caller acts on: `ok`/`proceed`; `needs_input`/`supply_input` (`missing` names the
+Outcomes the caller acts on: `ok`; `needs_input`/`supply_input` (`missing` names the
 field); `denied`/`stop`; `STATE_DRIFT` or `PLAN_EXPIRED` →
 `repreview`; a failed write: `WRITE_FAILED` with `stop` (a deterministic rejection; it replays,
-fix the input and use a new key) or `RATE_LIMITED` with `retry` (nothing was written: apply the
+fix the input and preview the corrected payload) or `RATE_LIMITED` with `retry` (nothing was written: apply the
 same plan again after the wait); a vendor that accepted an update but kept the old value (`FIELD_NOT_PERSISTED` with `stop`: the apply reads the stored record back and compares every field you sent; the write itself is `succeeded`, `data.record` shows what is stored and `data.notPersisted` names the fields — the apply re-reads twice, after waiting 0.75 s, then a further 1.5 s, before concluding, because the vendor read path can lag its write; re-read the record before repeating the update; a replay answers the same); an unknown outcome (`WRITE_OUTCOME_UNKNOWN`,
-`verify_then_repreview`): that plan is never sent again, and re-applying it or re-previewing under
-the same key only replays `unknown`. Re-read the target; if the write is absent, preview again under
-a new `idempotency_key` (a new attempt) after the 10-minute cooldown; its duplicate query refuses
-it if the first write did land. Payload field names are matched case-insensitively, and keys that
+`verify_then_repreview`): an identical plan is never sent again, even when previewed under a new
+handle. Re-read the target and verify in Autotask. A changed payload or changed stable vendor facts
+creates a different plan; it still waits for the 10-minute target cooldown after an unknown outcome.
+Payload field names are matched case-insensitively, and keys that
 differ only by case, or are not plain ASCII field names, are refused. `STATE_UNAVAILABLE` means the
 state dir could not be checked (`retry`) or the server's own registration in the state dir was removed (`stop`; see below). Use a separate Autotask API user for operator deployments, and run
 the live write leg on throwaway data before relying on it (B7 in the 0.6.0 plan).
 
+Upgrade note (#250): stop **all** processes sharing a state directory before upgrading and restart
+all on the same version. Mixed old/new versions are unsupported. Old pending plans must be previewed
+again. Existing ledger entries and historical chained audit lines remain on disk; new audit lines are
+plain JSONL. Old move snapshot files are inert and are not automatically deleted.
+
 #### The state lock: recovery
 
 Many processes may share a state dir (issue #68): every process registers its boot in a holder
@@ -243,7 +233,7 @@ The succession rules:
   lease is expired 15 s after the old container stopped, so the next boot takes the lock over on
   its own. With a new hostname (the docker default: the container id) the R6 host refusal applies
   and the operator deletes `<state dir>/lock` (the case below). Every takeover is appended to the
-  `audit.jsonl` hash chain as a `lock_takeover` line, and `/ready` reports the lock's age, holder
+  `audit.jsonl` log as a `lock_takeover` line, and `/ready` reports the lock's age, holder
   id, lease freshness and the holder count, so an orchestrator can tell a stale lock from a live
   one.
 
@@ -285,6 +275,8 @@ signal. Keep the rest of the state dir; `audit.jsonl` is the write history.
 
 ### Query results: TSV, `output_path` and the saved-file shape
 
+`autotask_query` always wraps untrusted text and uses the SDK's default transport and labels; `via`, `names`, and `untrusted_wrapper` are refused as unknown inputs.
+
 `autotask_query` answers `data.result` with the SDK's bounded-query envelope:
 
 ```
@@ -301,12 +293,11 @@ writes a result file on its own: when a result is too large, the MCP host persis
 tool result, and the file it writes holds this same envelope as JSON — so a saved result can be read
 back with exactly the fields above.
 
-Three per-call options change the result form:
+Two per-call options change the result form:
 
 | Option | Effect |
 |--------|--------|
 | `format: 'tsv'` | serves the table as `data.result.tsv` — a header row of column names plus one tab-separated line per record — with `result.columns` and `result.rowCount`, and **omits `result.items`** (that omission is the size saving; the JSON form stays the default). Inside a value a literal backslash is written as `\\`, a tab as `\t`, a newline as `\n` and a carriage return as `\r`; the `<untrusted_content>` markers survive inside cells. |
-| `untrusted_wrapper: false` | skips the `<untrusted_content>` wrapping for that call only; the result then carries `untrustedWrapper: 'disabled'` and the human text says so. Absent (the default) wraps exactly as before. |
 | `output_path: '<relative path>'` | **stdio transport only**: walks the FULL match set with the resource's own query iterator, writes the envelope JSON to a file under `AUTOTASK_OUTPUT_DIR`, and returns a summary (`outputPath`, `columns`, `rowCount`, the first rows, `bytes`) instead of the table. |
 
 `output_path` is deliberately strict: the deployment sets an **absolute** `AUTOTASK_OUTPUT_DIR`
@@ -335,7 +326,7 @@ so `O_EXCL` refuses it too.
 
 The walk stops at 10,000 rows with an explicit truncation note in the summary (`hasMore: true` then
 means the cap, not only the query limit). The call is refused outright on the `http` transport (the
-caller is a request, not the process owner), and it cannot be combined with `format`, `latest` or
+caller is a request, not the process owner), and it cannot be combined with `latest` or
 `note_chars` — one result form per call.
 
 The invoice export is the second `output_path` file kind (issue #54): `autotask_invoice_get` with
@@ -461,10 +452,9 @@ non-zero on an invalid config (fail-fast) instead of failing at the first tool c
 |----------|----------|---------|---------|
 | `MCP_TRANSPORT` | no | `http` | `stdio` or `http`; the CLI `--transport` flag overrides |
 | `AUTOTASK_PROFILE` | no | `readonly` | `readonly` or `operator` (see [Profiles and writes](#profiles-and-writes)) |
-| `AUTOTASK_WRITE` | operator | — | per-operation `allow`/`gate`/`deny` (see [docs/write-gate.md](docs/write-gate.md)) |
+| `AUTOTASK_WRITE` | operator | — | per-operation `allow`/`deny`; hard rules require human confirmation (see [docs/write-gate.md](docs/write-gate.md)) |
 | `AUTOTASK_DEDUP` | no | — | create duplicate-check fields, e.g. `companies.create:companyName` |
-| `AUTOTASK_WRITE_LIMITS` | no | — | write caps, e.g. `50/h,200/d` |
-| `AUTOTASK_TRUSTED_HOST_PROMPT` | no | — | `stdio` and client ids whose own prompt confirms a gated apply |
+| `AUTOTASK_EXPENSE_REPORT_SUBMITTER_PIN` | no | — | one resource id admitted for a company-less `expense_reports.create` (see [write-gate.md](docs/write-gate.md)) |
 | `AUTOTASK_STATE_DIR` | operator | — | the operator state dir (0700) |
 | `AUTOTASK_RUN_SCOPE` | operator on stdio or gateway | — | `{"companyIds":[...]}` or `{"all":true}` |
 | `AUTOTASK_PRINCIPAL` | no | `stdio` | the stdio operator principal |
@@ -478,10 +468,9 @@ non-zero on an invalid config (fail-fast) instead of failing at the first tool c
 | `AUTOTASK_BASE_URL` | stdio: yes · http: no (default origin) | — | the zone origin, e.g. `https://webservices6.autotask.net` (zone lives in the host; base path `/atservicesrest` is fixed — never configurable) |
 | `AUTOTASK_ALLOWED_BASE_HOSTS` | http: unless `AUTOTASK_ALLOW_ANY_BASE_HOST=true` | — | comma-separated exact hostnames or `*.suffix` subdomain suffixes a caller may name in `X-Autotask-Base-Url` (no scheme/port/path). Unset + default origin set → only that origin accepted. Unset + no default → boot refused unless the lab-only flag. **Recommended production value: `*.autotask.net`**. Literal private-IP origins are always refused. |
 | `AUTOTASK_ALLOW_ANY_BASE_HOST` | no | `false` | lab-only opt-in to boot with neither allow-list nor default origin; `warn`-logged at boot (decision D-4); refused with the operator profile. Not set in production. |
-| `AUTOTASK_CACHE_PRESET` | no | `on` | per-tenant in-process caches (see [Per-tenant pool & cache](#per-tenant-pool--cache)): `on` (default) sends no cache blocks — the SDK's default-on caches apply to each pooled tenant client (read ~5 min + the plan-derived reference table, field ~5 min, resource-name ~1 h); `off` opts every SDK cache channel out explicitly (every read re-dials the vendor) |
+| `AUTOTASK_CACHE` | no | `on` | the single off switch for the SDK's per-tenant in-process caches (see [Per-tenant pool & cache](#per-tenant-pool--cache)): `on` (default) sends no cache block — the SDK's default-on caches apply to each pooled tenant client (read ~5 min + the reference tables at 1 h, field metadata ~5 min); `off` sends `cache: false` (every read re-dials the vendor) |
 | `AUTOTASK_CLOSED_TICKET_STATUS_IDS` | no | unset | comma-separated ticket status ids that mean closed (e.g. `5,9`), pinning what the open-ticket parts of `autotask_resource_workload`, `autotask_contact_full_profile` and `autotask_company_full_profile` exclude; unset = read from the tenant's live status picklist (the ids used are reported in the part's `closedStatus`); if the picklist can't be read and nothing is pinned, `autotask_resource_workload` and `autotask_contact_full_profile` degrade the open-ticket part to `absent: CLOSED_STATUS_UNRESOLVED` rather than answer on a guessed id, while `autotask_company_full_profile` (which keeps the SDK's `allowAssumed: true`) answers on the SDK's assumed closed id and says so in the part's disclosure note |
 | `AUTOTASK_COMPOSITE_NAMES` | no | `off` | opt-in name/label siblings on the four SDK-backed composites (`tickets.fullContext`, `companies.fullProfile`, `configuration_items.profile`, `projects.getContext`) — reuses the SDK's existing caches (no new cache); `off` = byte-identical output to today; `on` adds the name siblings + the top-level `names` section, bounded by the SDK name-read budget (default 20 cold wire reads, lowerable only) |
-| `AUTOTASK_FIELD_CACHE_TTL_MS` | no | unset (SDK 5 min) | pass-through to the SDK's field-metadata cache TTL (positive integer ms), sent as the scalar `fieldCache` block on the `on` preset path only — the server holds no TTL value of its own: unset or invalid (non-integer, <= 0) sends no `fieldCache` block and the SDK default (5 min) applies; `off` keeps its explicit opt-out; `fieldCatalog` `fresh: true` still bypasses the cache |
 | `AUTOTASK_OUTPUT_DIR` | no | unset | the ONE directory the `output_path` option may write into (the bounded query tools and the invoice export; stdio transport only). Unset = defaults to `output/` under `AUTOTASK_STATE_DIR` (the feature refuses when neither is set); must be absolute, must already EXIST (the server never creates the root) and must not be the filesystem root. A caller path is relative to this root, and the root and target are canonically resolved (`realpath`) so a traversal or symlink escape is refused — with nothing created outside the root. See [Query results](#query-results-tsv-output_path-and-the-saved-file-shape) |
 | `AUTOTASK_RATE_LIMIT_PER_HOUR` | no | 8000 (agent profile) | override the SDK's local hourly budget (never above the vendor cap; `null`/off is rejected at boot — it would void the budget guard) |
 | `AUTOTASK_MAX_CONCURRENT` | no | 3 (agent profile) | override the SDK's local concurrency bound |
@@ -641,17 +630,16 @@ security decision D-1 ratified): a bounded **in-process** client pool with a per
 cache, because a fresh client per request would silently disable the SDK's local vendor-budget
 guards (rate limiter, 429 cooldown) — a worse security posture, not a safer one.
 
-- **Pool** — `createClientPool` from `node-autotask/pool`: bounded LRU (default `maxSize` 128; the
-  server may lower it). Key = SHA-256 digest of the **normalised credential tuple**
-  (user, integration code, secret, resolved base URL, impersonation id). Optional idle TTL (lazy,
-  no timers). Eviction is logged without values. A vendor `401` (or an impersonation-scope `403`)
-  deletes the entry (no negative caching).
-- **Cache** — `AUTOTASK_CACHE_PRESET=on` (default) sends no cache blocks — the SDK's default-on
-  caches apply to each pooled tenant client (the reference TTL table moved into the SDK with
-  0.9.0's default-on change: structural ~1 h / mutable ~5 min, field ~5 min, resource-name ~1 h).
-  Repeated reads of the same record are served from that tenant's cache until TTL expiry; composites
-  de-duplicate their 3–8 fan-out reads through it. `off` opts every SDK cache channel out explicitly
-  (every read re-dials the vendor).
+- **Pool** — the SDK's `createClientPool` (no server-side wrapper; issue #252): a bounded LRU of
+  tenant clients at the SDK default `maxSize` 128. Key = SHA-256 digest of the
+  **normalised credential tuple** (user, integration code, secret, resolved base URL,
+  impersonation id). Eviction is logged without values. A vendor `401` (or an
+  impersonation-scope `403`) deletes the entry (no negative caching).
+- **Cache** — `AUTOTASK_CACHE=on` (default) sends no cache block — the SDK's default-on caches
+  apply to each pooled tenant client (SDK 0.9.0's default-on change: read ~5 min, the reference
+  tables ~1 h, field metadata ~5 min). Repeated reads of the same record are served from that
+  tenant's cache until TTL expiry; composites de-duplicate their 3–8 fan-out reads through it.
+  `off` sends `cache: false` (every read re-dials the vendor).
 - **Boundaries — never relaxed:** in-process only (never on disk), **per-tenant** (one tenant's
   cached records or limiter state can never answer another tenant's request), TTL-bounded, cleared
   on eviction and on `401`. The same boundary covers the limiter/cooldown state.
@@ -710,12 +698,11 @@ guards (rate limiter, 429 cooldown) — a worse security posture, not a safer on
   liveness-only healthcheck (no vendor call), direct `SIGTERM` (stop accepting, 2 s bounded drain of
   in-flight work, exit 0), TLS termination at the gateway on a private unpublished network.
 - **Supply chain:** `node-autotask` is the only **vendor** runtime dependency (the other two are
-  `@modelcontextprotocol/server` and `zod`); the pre-publish checklist
-  (manual — this repo has no CI) asserts it carries **zero runtime dependencies** and **no install
-  lifecycle hooks**, asserts the resolved `@modelcontextprotocol/server` version is ≥ 2.3.0 (the
+  `@modelcontextprotocol/server` and `zod`); the pre-publish checklist asserts it carries **zero
+  runtime dependencies** and **no install lifecycle hooks**, asserts the resolved `@modelcontextprotocol/server` version is ≥ 2.3.0 (the
   baseline that serves the era pair on one endpoint), runs a production dependency audit, and
-  scans the image. This repo ships no GitHub Actions workflow; quality gates and publishing are
-  run manually by the maintainer.
+  scans the image. CI (`.github/workflows/ci.yml`) runs the full gate on every PR; npm releases are
+  published only by the tag-triggered release workflow (see [docs/RELEASING.md](docs/RELEASING.md)).
 
 Full control set: [`docs/architecture.md`](docs/architecture.md) (sections 7.3, 8 and 10).
 
@@ -737,10 +724,9 @@ mirrored-surface re-review, gates), not a range float: see the
 
 ## Development
 
-- Node **24** (current LTS; the SDK requires `node >= 24`), **pnpm 10**. The `pnpm-lock.yaml` is
-  committed with the first `node-autotask` publish (S8/C8.2); until then installs resolve without
-  a lockfile and the install step says so explicitly (reproducibility via the committed lockfile
-  is a pre-publish requirement; gates run manually — no CI in this repo).
+- Node **24** (current LTS; the SDK requires `node >= 24`), **pnpm 10**. `pnpm-lock.yaml` is committed
+  and installs are frozen (`pnpm install --frozen-lockfile`). `pnpm verify` is the full gate; CI runs it on
+  every PR and push to `main`.
 - `pnpm i` — install · `pnpm build` — compile to `dist/` · `pnpm typecheck` · `pnpm lint`
 - Tests: `pnpm test` (all) or per suite: `pnpm exec vitest run test/unit` / `test/integration` /
   `test/conformance`. **No live vendor API and no credentials are ever required** — every suite

package/capabilities.json

@@ -4,9 +4,9 @@
   "description": "Machine-readable capability catalogue for iit-mcp-autotask: the tools the server can serve, with the toolset and the lowest profile that serves each. Everything else in the registry is reachable through the generic layer (autotask_catalog / autotask_describe / autotask_read) and documented in docs/capability-matrix.md. Generated from src/tools/surface.ts by scripts/build-capabilities.mjs.",
   "exposedToolCount": {
     "readonlyCore": 10,
-    "readonlyAll": 17,
+    "readonlyAll": 18,
     "operatorCore": 12,
-    "operatorAll": 19
+    "operatorAll": 20
   },
   "profiles": {
     "readonly": {
@@ -40,7 +40,8 @@
     ],
     "finance": [
       "autotask_quote_get",
-      "autotask_invoice_get"
+      "autotask_invoice_get",
+      "autotask_revenue_rollup"
     ],
     "operator": [
       "autotask_write",
@@ -67,7 +68,7 @@
     },
     {
       "id": "autotask.platform.catalog",
-      "description": "Find the exact operation key for anything without a dedicated tool: ranked search (q) over the 1,281 registry operations, with effect and whether this deployment serves it. No vendor call.",
+      "description": "Find the exact operation key for anything without a dedicated tool: ranked search (q) over the 1,280 registry operations, with effect and whether this deployment serves it. No vendor call.",
       "mcpPrimitive": "tool",
       "toolName": "autotask_catalog",
       "type": "read",
@@ -99,7 +100,7 @@
     },
     {
       "id": "autotask.generic.read",
-      "description": "Run reads by exact registry key, or up to 10 in one call: unbilled work, profitability and margin, SLA health. *.query: 50 rows; scope by company/contract ids (unscoped = tenant walk); totals: autotask_query group_by; slim: includeFields, noteChars.",
+      "description": "Run one or several reads in one call by exact registry key: unbilled work, profitability and margin, SLA health. Scope by company/contract ids (unscoped = tenant walk); totals: autotask_query group_by; slim: includeFields, noteChars.",
       "mcpPrimitive": "tool",
       "toolName": "autotask_read",
       "type": "read",
@@ -179,7 +180,7 @@
     },
     {
       "id": "autotask.company.full_profile",
-      "description": "One company with locations, contacts, notes, open tickets and projects, 10 rows per part (capped: true = more exist; raise the limit). fields {part:[names]} trims columns. Open = not tenant-closed. Missing parts degrade to typed absent.",
+      "description": "One company with locations, contacts, notes, open tickets and projects (capped: true = more exist; raise the limit). fields {part:[names]} trims columns. Open = not tenant-closed. Missing parts degrade to typed absent.",
       "mcpPrimitive": "tool",
       "toolName": "autotask_company_full_profile",
       "type": "read",
@@ -195,7 +196,7 @@
     },
     {
       "id": "autotask.resource.workload",
-      "description": "A resource's open tickets (primary or secondary, de-duplicated), assignments, time off. For \"how many\" use totals (exact; capped = link cap hit, not row capped; extra reads, up to 20 pages; totalsAbsent = failed). Missing parts: typed absent.",
+      "description": "A resource's open tickets (primary or secondary, de-duplicated), assignments, time off. For \"how many\" use totals (exact; capped = link cap hit, not row capped; extra reads; totalsAbsent = failed). Missing parts: typed absent.",
       "mcpPrimitive": "tool",
       "toolName": "autotask_resource_workload",
       "type": "read",
@@ -243,7 +244,7 @@
     },
     {
       "id": "autotask.contact.full_profile",
-      "description": "One contact with their company and open tickets (closed set from the tenant status picklist, 2-5 reads). Contains personal data. Missing parts degrade to typed absent.",
+      "description": "One contact with their company and open tickets (closed set from the tenant status picklist). Contains personal data. Missing parts degrade to typed absent.",
       "mcpPrimitive": "tool",
       "toolName": "autotask_contact_full_profile",
       "type": "read",
@@ -275,7 +276,7 @@
     },
     {
       "id": "autotask.contract.full_profile",
-      "description": "One contract with services, billing rules, the 50 newest charges and service units. Monthly P&L: autotask_read (guide: contract-profitability).",
+      "description": "One contract with services, billing rules, newest charges and service units. Monthly P&L: autotask_read (guide: contract-profitability).",
       "mcpPrimitive": "tool",
       "toolName": "autotask_contract_full_profile",
       "type": "read",
@@ -321,6 +322,22 @@
         "openWorld": true
       }
     },
+    {
+      "id": "autotask.finance.revenue_rollup",
+      "description": "Revenue for recurring and fixed price contracts by vertical, company or month, with excluded amounts and coverage. One scope required; full-month windows in the user zone. May take 15-45 seconds. Finance playbook: revenue-rollup.",
+      "mcpPrimitive": "tool",
+      "toolName": "autotask_revenue_rollup",
+      "type": "read",
+      "toolset": "finance",
+      "profile": "readonly",
+      "backingOperation": "operations.revenueRollup",
+      "annotations": {
+        "readOnly": true,
+        "idempotent": true,
+        "destructive": false,
+        "openWorld": true
+      }
+    },
     {
       "id": "autotask.generic.write",
       "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.",
@@ -361,7 +378,7 @@
       "autotask_describe",
       "autotask_read"
     ],
-    "backingRegistryOperations": 1281,
+    "backingRegistryOperations": 1280,
     "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/gate.d.ts

@@ -1,6 +1,6 @@
 import { type ClientCapabilities, type InputRequiredResult } from '@modelcontextprotocol/server';
 import { type ToolReturn } from '../tools/results/envelope.js';
-import type { Confirmation } from '../tools/write/apply-phases.js';
+import type { Confirmation } from '../tools/write/apply.js';
 import type { PlanRecord } from '../write/store.js';
 /** The key the confirm form's answer rides under in `inputResponses`. */
 export declare const GATE_KEY = "confirm";
@@ -23,7 +23,6 @@ export declare function formElicitation(extra: unknown, caller: Caller, legacyCa
 export declare function gateApply(a: {
     plan: PlanRecord;
     caller: Caller;
-    trusted: ReadonlySet<string>;
     extra: unknown;
     legacyCaps: ClientCapabilities | undefined;
 }): GateOutcome;

package/dist/access/gate.js

@@ -1,19 +1,9 @@
-/**
- * access/gate.ts — the apply-time human gate for a gated plan (#178).
- *
- * A trusted caller's own host prompt counts as the confirmation (AUTOTASK_TRUSTED_HOST_PROMPT). Any
- * other caller whose client shows form elicitation gets one plain confirm form through the SDK's
- * multi-round-trip `input_required` result, and the client retries the same call with the answer.
- * The plan is already held on the server, so there is no code, key or `requestState` to carry.
- * Everything else is a typed `GATE_UNSUPPORTED` deny: an untrusted 2025-era client over HTTP
- * included, because the legacy shim cannot push a request from a stateless per-request instance.
- */
+/** Apply-time human confirmation through MCP form elicitation; unsupported clients fail closed. */
 import * as z from 'zod';
 import { inputRequired } from '@modelcontextprotocol/server';
 import { cleanUntrustedText } from '../tools/results/untrusted.js';
 import {} from '../tools/results/envelope.js';
 import { answer, reason } from '../tools/write/common.js';
-import { approvalDigest } from '../write/canonical.js';
 /** The key the confirm form's answer rides under in `inputResponses`. */
 export const GATE_KEY = 'confirm';
 const DATA_CAP = 500;
@@ -53,24 +43,20 @@ export function formElicitation(extra, caller, legacyCaps) {
 }
 /** Decide one gated plan's apply: a confirmation, the confirm form, or a typed deny. Zero vendor calls on every path. */
 export function gateApply(a) {
-    const { plan, caller, trusted, extra, legacyCaps } = a;
-    const digest = approvalDigest(plan.planHash, plan.facts);
+    const { plan, caller, extra, legacyCaps } = a;
     const deny = (code, detail) => ({
         result: answer('denied', 'stop', [reason(code, detail)], { operation: plan.op, targets: plan.targets, plan: plan.handle }, { plan: plan.handle, planHash: plan.planHash }),
     });
-    if ((caller.transport === 'stdio' && trusted.has('stdio')) || (caller.transport === 'http' && caller.clientId !== undefined && trusted.has(caller.clientId))) {
-        return { ok: { via: 'host_prompt', digest } };
-    }
     // an answer counts only from a client that declared form elicitation; it is untrusted input, so only an explicit accept confirms
     if (formElicitation(extra, caller, legacyCaps)) {
         const response = extra?.mcpReq?.inputResponses?.[GATE_KEY];
         if (response !== undefined) {
             if (response?.action === 'accept')
-                return { ok: { via: 'elicitation', digest } };
+                return { ok: { via: 'elicitation', planHash: plan.planHash } };
             return deny('GATE_DECLINED', `the person declined or dismissed ${plan.op}; nothing was sent`);
         }
         return { result: inputRequired({ inputRequests: { [GATE_KEY]: inputRequired.elicit({ message: gateMessage(plan), requestedSchema: z.object({}) }) } }) };
     }
-    return deny('GATE_UNSUPPORTED', `${plan.op} needs a person to confirm it, and this client cannot show a confirm form (and is not a trusted host); nothing was sent`);
+    return deny('GATE_UNSUPPORTED', `${plan.op} needs a person to confirm it, and this client cannot show a confirm form; nothing was sent`);
 }
 //# sourceMappingURL=gate.js.map

package/dist/access/write-env.d.ts

@@ -1,5 +1,5 @@
 import { type WriteShape } from '../write/hard-rules.js';
-export type WriteMode = 'allow' | 'gate' | 'deny';
+export type WriteMode = 'allow' | 'deny';
 export interface ResolvedOp {
     mode: WriteMode;
     rule: string;
@@ -7,21 +7,16 @@ export interface ResolvedOp {
     upgraded?: true;
     dedup?: readonly string[];
 }
-export interface WriteLimits {
-    perHour?: number;
-    perDay?: number;
-}
+/** `expensePin`: the one submitter id a company-less `expense_reports.create` is admitted for (absent = no exception). */
 export interface LoadedPolicy {
     table: ReadonlyMap<string, ResolvedOp>;
-    limits?: WriteLimits;
+    expensePin?: number;
     policyHash: string;
 }
 export declare function resolveWritePolicy(env: {
     write: string;
     dedup?: string;
-    limits?: string;
+    expensePin?: string;
 }): LoadedPolicy;
-/** The trusted host-prompt ids (`stdio` or a connection id), comma separated. */
-export declare function parseTrustedHosts(raw: string | undefined): ReadonlySet<string>;
-/** A `gate` row, or a non-deny move row (a move can escalate to a gate). */
+/** Any permitted write whose hard rule requires a human, or a move that can escalate. */
 export declare const anyGate: (loaded: LoadedPolicy) => boolean;