@dotcms/ai — Productionize the Agentic Runtime

[fmontes]

Description

Context. @dotcms/ai is the runtime that runs model- and human-written code safely against dotCMS — the foundation under every agentic surface we ship.

Problem. The runtime exists only as an internal prototype (libs/agentic-tools): private, lower-level than it should be, with hardening gaps (per-call worker re-eval, no abort, no resource limits, thin test coverage) that block any "production" claim. There's no public package, and apps/mcp-server duplicates wiring the runtime should own.

Value. Every other CMS ships fixed tools; only dotCMS lets the model compose new operations as code, governed by construction. This epic ships that as a public SDK.

Solution (high level).

• Move + rename libs/agentic-tools → libs/sdk/ai / @dotcms/agentic-tools → @dotcms/ai (public, no shim — internal name, no external consumers).
• Public surface: one package, subpath exports; one runtime, two verbs (request() direct, run(code) sandboxed) sharing a single request core so they can't diverge; typed defineAdapter (Zod) that doubles as the tool definition.
• Harden + specify production contracts: worker pool, abort, resource limits, error model, observability, semver/support matrix.
• Prove it by migrating apps/mcp-server onto the new front door in the same PR.

Threat model (decided): capability confinement for trusted code generators, documented honestly — not adversarial isolation.

Out of scope:

• The MCP v2 product — skills, whitelist, distribution (separate epic, MCP Server v2 — Code Mode, Skills, and Agent Governance #36078; the mcp-server migration here is the shared proof-point).
• The a11y/GEO agents and their UIs (consumers of this runtime).
• The no-code Agent Builder GUI.
• Any LLM inside the runtime (BYO-model is separate and already shipped).
• Merging with @dotcms/client (the content SDK lives beside this, not on top).

Desired Outcome

• apps/mcp-server runs on @dotcms/ai in production, no behavior regression.
• @dotcms/ai is published (subpath exports, dual ESM/CJS, public-API audit done); libs/agentic-tools is deleted.
• One shared request core is the only request path — request() and run() provably can't diverge.
• Threat-model boundary documented honestly in the shipped package.

Target Personas

• Developer teams
• Content teams
• DevOps teams
• System administrators (dotCMS)

Links

• Asana epic
• Related: MCP Server v2 epic — MCP Server v2 — Code Mode, Skills, and Agent Governance #36078 (consumer product; runs on this runtime)

[github-actions]

PRs linked to this issue

• feat(ai): @dotcms/ai agentic runtime + mcp-server migration by @fmontes