From 54c5b3c786d2bab5f3210df352f2c002b1ef673c Mon Sep 17 00:00:00 2001 From: Karl Kemister-Sheppard Date: Thu, 5 Nov 2026 16:50:13 +1000 Subject: [PATCH 1/9] TINYDOC-3686: Correct the TinyMCE AI pages against the hosted API spec, the plugin, and AI service image 1.3.0. --- modules/ROOT/pages/tinymceai-actions.adoc | 4 +++- .../ROOT/pages/tinymceai-api-overview.adoc | 4 ++-- modules/ROOT/pages/tinymceai-chat.adoc | 8 +++++++- modules/ROOT/pages/tinymceai-limits.adoc | 9 +++++++-- modules/ROOT/pages/tinymceai-models.adoc | 6 ++++-- ...tinymceai-on-premises-getting-started.adoc | 2 +- .../pages/tinymceai-on-premises-hooks.adoc | 3 ++- .../ROOT/pages/tinymceai-on-premises-jwt.adoc | 5 ++--- .../ROOT/pages/tinymceai-on-premises-mcp.adoc | 10 +++++++--- .../tinymceai-on-premises-production.adoc | 15 +++++++++++++-- .../tinymceai-on-premises-providers.adoc | 19 ++++++++----------- .../tinymceai-on-premises-reference.adoc | 18 +++++++++--------- ...tinymceai-on-premises-troubleshooting.adoc | 4 ++-- modules/ROOT/pages/tinymceai-on-premises.adoc | 2 +- modules/ROOT/pages/tinymceai-permissions.adoc | 4 ++-- modules/ROOT/pages/tinymceai-review.adoc | 12 ++++++++---- modules/ROOT/pages/tinymceai-streaming.adoc | 12 ++++++++++++ modules/ROOT/pages/tinymceai-usage.adoc | 2 +- 18 files changed, 91 insertions(+), 48 deletions(-) diff --git a/modules/ROOT/pages/tinymceai-actions.adoc b/modules/ROOT/pages/tinymceai-actions.adoc index 3d8ad3dc01..ab773fd2d3 100644 --- a/modules/ROOT/pages/tinymceai-actions.adoc +++ b/modules/ROOT/pages/tinymceai-actions.adoc @@ -272,7 +272,7 @@ In addition to system actions, custom actions can be created for specific use ca Unlike system actions that use default identifiers, custom actions use a unified endpoint, https://tinymceai.api.tiny.cloud/v1/docs#tag/Actions/operation/callCustomAction[Call a custom action], where the transformation behavior is defined through a prompt parameter. See https://tinymceai.api.tiny.cloud/v1/docs#tag/Actions[Actions API] for the custom actions endpoint and implementation details. -Custom actions require the `ai:actions:custom` permission in the JWT token. See xref:tinymceai-permissions.adoc#actions-permissions[Actions permissions]. +Custom actions require the `ai:actions:custom` permission and the permission for the requested model in the JWT token. See xref:tinymceai-permissions.adoc#actions-permissions[Actions permissions] and xref:tinymceai-permissions.adoc#model-permissions[Model permissions]. [[actions-streaming]] === Streaming Responses @@ -284,6 +284,8 @@ Actions use Server-Sent Events (SSE) for real-time streaming results. See the xr The https://tinymceai.api.tiny.cloud/v1/docs#tag/Actions[Actions API] reference (interactive OpenAPI documentation) is the full source for system and custom action endpoints, request and response schemas, authentication, worked examples, and streaming action responses. +To record user feedback on a result, https://tinymceai.api.tiny.cloud/v1/docs#tag/Actions/operation/addSystemActionRating[rate a system action call] or https://tinymceai.api.tiny.cloud/v1/docs#tag/Actions/operation/addCustomActionRating[rate a custom action call] with the `+callId+` from the `+action-metadata+` event of the action stream. + [[related-features]] == Related Features diff --git a/modules/ROOT/pages/tinymceai-api-overview.adoc b/modules/ROOT/pages/tinymceai-api-overview.adoc index 013bb8351c..94164ea13a 100644 --- a/modules/ROOT/pages/tinymceai-api-overview.adoc +++ b/modules/ROOT/pages/tinymceai-api-overview.adoc @@ -41,7 +41,7 @@ The following pages cover the AI service architecture and configuration. [[versioning]] == Versioning -The version of each endpoint is part of its path, for example `+/v1/conversations+`. The {pluginname} plugin calls the `+/v1+` endpoints, and requests the model list with compatibility version `+1+`. The compatibility version is separate from the endpoint version. See xref:tinymceai-models.adoc#model-compatibility-versions[Model compatibility versions]. +The version of each endpoint is part of its path, for example `+/v1/conversations+`. The {pluginname} plugin calls the `+/v1+` endpoints, and requests the model list with compatibility version `+1+`. The compatibility version is separate from the endpoint version. Conversation messages also have version 1.1 endpoints under `+/v1.1+`, which can resume and cancel a reply stream. See xref:tinymceai-streaming.adoc#resumable-streams[Resumable reply streams]. See xref:tinymceai-models.adoc#model-compatibility-versions[Model compatibility versions]. [[pagination]] == Pagination @@ -102,7 +102,7 @@ The API reference lists every code in its https://tinymceai.api.tiny.cloud/v1/do [[rate-limit-errors]] === Rate limit errors -For `+429+` responses with the code `+rate-limits-exceeded+`, see xref:tinymceai-limits.adoc#handling-rate-limit-errors[Handling rate limit errors]. +For `+429+` responses with the code `+rate-limits-exceeded+`, see xref:tinymceai-limits.adoc#handling-rate-limit-errors[Handling rate limit errors]. For `+403+` responses with the code `+usage-limits-exceeded+`, see xref:tinymceai-limits.adoc#usage-limits[Usage limits]. [[resources-and-support]] == Resources and support diff --git a/modules/ROOT/pages/tinymceai-chat.adoc b/modules/ROOT/pages/tinymceai-chat.adoc index c90a06a273..54f24d694d 100644 --- a/modules/ROOT/pages/tinymceai-chat.adoc +++ b/modules/ROOT/pages/tinymceai-chat.adoc @@ -96,7 +96,7 @@ tinymce.init({ Web search in Chat allows the AI to access and retrieve real-time information from the internet. Instead of relying only on pre-trained knowledge, the model can search the web to find up-to-date facts, verify details, and provide more accurate, current answers. -Some models use web search automatically, while others may require manual activation. Whether the **Web search** toggle image:icons-premium/web-search.svg[Web search icon,24px] below the prompt input needs to be toggled depends on the model and sometimes even how the prompt is worded. For models that support web search, use the toggle button to enable it. +The model searches the web only when web search is enabled for the message. For models that support web search, turn on the **Web search** toggle image:icons-premium/web-search.svg[Web search icon,24px] below the prompt input. [[reasoning]] === Reasoning @@ -302,6 +302,8 @@ The `+capabilities+` object of a https://tinymceai.api.tiny.cloud/v1/docs#tag/Co Web search is separate from the https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Web-Resources[Conversation Web Resources] endpoints, which attach the content of one known URL to the conversation. +A message request can also pass `+extraHttpHeaders+` so the service can download images in the message content that require authentication. + [[conversations-api-stored]] === Working with stored conversations @@ -310,12 +312,16 @@ The Chat history in the sidebar shows the conversations and messages that the AI * https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversations/operation/getConversations[List conversations]. * https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversations/operation/getConversation[Get a conversation], https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversations/operation/updateConversation[update a conversation] (for example, to rename or pin it), or https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversations/operation/deleteConversation[delete a conversation]. * https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Messages/operation/getMessages[List the messages in a conversation]. +* https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Messages/operation/addConversationMessageRating[Rate a reply] or https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Messages/operation/updateMessage[update a message]. +* For back-end administration, a token with the `+ai:admin+` permission can https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Admin/operation/adminListConversations[list], https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Admin/operation/AdminGetConversation[get], and https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Admin/operation/adminDeleteConversation[delete] the conversations of any user. Never return an `+ai:admin+` token to the editor. See xref:tinymceai-permissions.adoc#admin-permissions[Admin permissions]. [[conversations-streaming]] === Streaming Responses Conversations use Server-Sent Events (SSE) for real-time streaming responses. See the xref:tinymceai-streaming.adoc[Streaming Responses guide] for detailed implementation information and code examples. For the events and their payloads, see https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Messages/operation/createMessage[Send a message] in the API reference. +With version 1.1 of the message endpoints, a client can resume an interrupted reply or cancel one in progress, when replay is available for that reply. See xref:tinymceai-streaming.adoc#resumable-streams[Resumable reply streams]. + [[conversations-api-reference]] === API Reference diff --git a/modules/ROOT/pages/tinymceai-limits.adoc b/modules/ROOT/pages/tinymceai-limits.adoc index 6f29752549..5f0908abed 100644 --- a/modules/ROOT/pages/tinymceai-limits.adoc +++ b/modules/ROOT/pages/tinymceai-limits.adoc @@ -20,7 +20,12 @@ NOTE: Specific rate limit values are subject to change and may vary based on the [[handling-rate-limit-errors]] === Handling rate limit errors -A request over a rate limit fails with HTTP status `+429 Too Many Requests+` and the error code `+rate-limits-exceeded+`. The `+data.limits+` array in the error body names each limit that the request exceeded, for example `+[{ "name": "messages-per-minute" }]+`, and the `+action+` field reads `+Try again later.+` For the other fields of the error body, see xref:tinymceai-api-overview.adoc#error-responses[Error responses]. The API reference lists this response for https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Messages/operation/createMessage[sending conversation messages] and for https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Web-Resources/operation/downloadWebResources[adding web resources to a conversation]. +A request over a rate limit fails with HTTP status `+429 Too Many Requests+` and the error code `+rate-limits-exceeded+`. The `+data.limits+` array in the error body names each limit that the request exceeded, for example `+[{ "name": "messages-per-minute" }]+`, and the `+action+` field reads `+Try again later.+` For the other fields of the error body, see xref:tinymceai-api-overview.adoc#error-responses[Error responses]. The API reference lists this response for https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Messages/operation/createMessage[sending conversation messages], for https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Messages-V1.1/operation/createMessageV2[sending conversation messages (V1.1)], and for https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Web-Resources/operation/downloadWebResources[adding web resources to a conversation]. + +[[usage-limits]] +=== Usage limits + +When the usage of an environment exceeds its limit for the current billing period, the service blocks the environment. Requests then fail with HTTP status `+403+` and the error code `+usage-limits-exceeded+`. The error body includes the environment ID and a `+data.usageExceededTo+` timestamp, and the `+action+` field asks to contact customer support or upgrade the plan. To track usage before the limit is reached, see xref:tinymceai-usage.adoc[Usage]. [[context-limits]] == Context Limits @@ -32,7 +37,7 @@ Context limits control how much content can be attached to conversations to ensu Supported attachment types include PDF, DOCX, PNG, JPEG, Markdown, HTML, and plain text. The API accepts files of up to 25 MB in a single upload to a conversation. Exact per-file, per-conversation, and PDF page limits also depend on the model in use. Read the `+limits+` object for that model from `GET /v1/models/\{version}` (see xref:tinymceai-models.adoc#verifying-model-limits-for-integration[Verifying limits for a configured model] and xref:tinymceai-models.adoc#model-information[Model Information]). For schema details, see the https://tinymceai.api.tiny.cloud/v1/docs#tag/Models[Models API] OpenAPI documentation. -The file picker in the {pluginname} plugin offers only the supported attachment types. The service enforces the file size and page count limits. +The file picker in the {pluginname} plugin offers only the supported attachment types. The service enforces the file size and page count limits. A request over these limits fails with HTTP status `+413+`. See xref:tinymceai-api-overview.adoc#error-codes[Error codes]. [[context-optimization-tips]] === Context Optimization Tips diff --git a/modules/ROOT/pages/tinymceai-models.adoc b/modules/ROOT/pages/tinymceai-models.adoc index acff8de355..f7950bcb47 100644 --- a/modules/ROOT/pages/tinymceai-models.adoc +++ b/modules/ROOT/pages/tinymceai-models.adoc @@ -252,7 +252,7 @@ Plugin configuration, API parameters, and per-feature options do not grant acces [NOTE] ==== -The set of models and capabilities can change between major {productname} releases. That kind of change is not treated as a breaking change for the editor. Use the plugin's model selection dropdown or `GET /v1/models/\{version}` to see what the environment offers and the model limitations. +The set of models and capabilities can change with AI service releases, independent of {productname} releases. That kind of change is not treated as a breaking change for the editor. Use the plugin's model selection dropdown or `GET /v1/models/\{version}` to see what the environment offers and the model limitations. ==== .Example: Set default model in plugin configuration @@ -296,7 +296,7 @@ Follow these steps to read limits and capabilities for the model the integration * *Align base URL and credentials* ** Call the same HTTP base URL the editor uses for {pluginname} requests. If the base URL and JWT do not belong to the same environment, the response is an authorization error rather than model metadata. * *List models for the compatibility version* -** Request `+GET /v1/models/1+`, the compatibility version that the {pluginname} plugin uses. To read a single model, request `+GET /v1/models/1/{id}+`. +** Request `+GET /v1/models/1+`, the compatibility version that the {pluginname} plugin uses. To read a single model, request `+GET /v1/models/1/{id}+`. See https://tinymceai.api.tiny.cloud/v1/docs#tag/Models/operation/getAiModel[Fetch a model]. * *Pick the matching `items[]` entry* ** In the JSON `items` array, select the object whose `id` matches the model in configuration (`tinymceai_default_model`) or in API bodies (`model`). * *Read `limits` and `capabilities`* @@ -449,6 +449,8 @@ Authorization: Bearer See xref:#model-capabilities[Model capabilities] for the model support and token scopes that each capability needs. +The `+reasoning+` capability accepts an optional `+level+`. Without it, the service uses the `+balanced+` level. For the accepted values, see https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Messages/operation/createMessage[Send a message]. + [[model-information]] === Model Information diff --git a/modules/ROOT/pages/tinymceai-on-premises-getting-started.adoc b/modules/ROOT/pages/tinymceai-on-premises-getting-started.adoc index 08e28dbd57..252c188b30 100644 --- a/modules/ROOT/pages/tinymceai-on-premises-getting-started.adoc +++ b/modules/ROOT/pages/tinymceai-on-premises-getting-started.adoc @@ -252,7 +252,7 @@ The AI service isolates users into Environments. Each environment has its own ac . Open the Management Panel: *http://localhost:8000/panel/* . Sign in using the `MANAGEMENT_SECRET` from `.env`. . Click *Create Environment* and give it a name (for example "Development"). -. Note the *Environment ID* displayed (a short identifier like `viOu8BnjJHb0HGK091p`). +. Note the *Environment ID* displayed (an identifier of 20 to 60 characters, such as `viOu8BnjJHb0HGK091pQ`). . Inside the environment, click *Create a new access key*. . *Copy the Environment ID and Access Key*. diff --git a/modules/ROOT/pages/tinymceai-on-premises-hooks.adoc b/modules/ROOT/pages/tinymceai-on-premises-hooks.adoc index 5e1d647a19..a1260922c2 100644 --- a/modules/ROOT/pages/tinymceai-on-premises-hooks.adoc +++ b/modules/ROOT/pages/tinymceai-on-premises-hooks.adoc @@ -11,6 +11,7 @@ The `+HOOKS+` environment variable configures hooks on the AI service container. == Requirements +* *AI service image version 1.3.0 or later.* Hooks were added in image version 1.3.0. * *An HTTPS endpoint hosted by the integrator.* The AI service does not include a hook endpoint. The endpoint accepts a `+POST+` request with a JSON body and responds with a decision. * *A response within the timeout.* Every chat turn waits for the endpoint. Measure the response time of the hook service before enabling hooks. * *A shared secret.* The AI service signs every request with it, and the endpoint uses it to reject requests that did not come from the AI service. See <>. @@ -715,7 +716,7 @@ The AI service calls the hook endpoint before xref:tinymceai-on-premises-moderat The {pluginname} plugin needs no configuration for hooks. A `+halt+` reply and a `+continue+` reply both appear in the chat as assistant messages. * A custom chat interface built on the REST API can read `+hook-progress+` events and show each line. See xref:tinymceai-streaming.adoc[Streaming]. -* To send custom front-end data in the hook request, attach `+delegation-context+` parts to messages through the conversation API. +* To send custom front-end data in the hook request, attach `+delegation-context+` parts to messages through the conversation API. See https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Messages/operation/createMessage[Send a message] in the API reference. [[troubleshooting]] == Troubleshooting diff --git a/modules/ROOT/pages/tinymceai-on-premises-jwt.adoc b/modules/ROOT/pages/tinymceai-on-premises-jwt.adoc index 0f697459e5..da37e2e193 100644 --- a/modules/ROOT/pages/tinymceai-on-premises-jwt.adoc +++ b/modules/ROOT/pages/tinymceai-on-premises-jwt.adoc @@ -68,10 +68,10 @@ Every token MUST contain the following claims. [cols=",,",options="header",] |=== |Claim |Type |Description -|`aud` |string |The Environment ID, copied from the Management Panel (for example `viOu8BnjJHb0HGK091p`). Type *must be string*, not array; the verifier rejects array-shaped `aud` (the default in some JWT libraries) with `invalid-jwt-payload`. +|`aud` |string |The Environment ID, copied from the Management Panel (for example `viOu8BnjJHb0HGK091pQ`). Type *must be string*, not array; the verifier rejects array-shaped `aud` (the default in some JWT libraries) with `invalid-jwt-payload`. |`iat` |number |Issued-at, seconds since epoch (UTC). |`exp` |number |Expiry, seconds since epoch (UTC). Recommend `iat {plus} 3600` for demos, `iat {plus} 900` for production. The server applies 60 seconds of clock-skew leeway; tokens up to 60 seconds past `exp` still verify. -|`sub` |string |Unique, stable user identifier. Conversation history is isolated per-`sub`; do not reuse one `sub` across users or conversations will leak between them. Do not include personally identifiable information (PII), such as names or email addresses, in the `sub` value, because the AI service logs it. Use an opaque identifier, such as an internal user ID. +|`sub` |string |Unique, stable user identifier, at most 96 characters. Conversation history is isolated per-`sub`; do not reuse one `sub` across users or conversations will leak between them. Do not include personally identifiable information (PII), such as names or email addresses, in the `sub` value, because the AI service logs it. Use an opaque identifier, such as an internal user ID. |`auth.ai.permissions` |`string[]` |Array of feature permission strings. See the permissions reference below. Wildcards (`+*+`) are accepted only in the documented positions; the bare string `"*"` is rejected. |=== @@ -881,7 +881,6 @@ When debugging, start here. Most "auth failures" reflect wrong claim values rath |HTTP 500 error on every endpoint |`auth.ai.permissions` is not an array of strings |Must be ``string[]``. Not a single string. Not `useAllFeatures`. |HTTP 403 `no-permissions-defined` |The token has no `auth` claim, no `permissions` key, or an empty `permissions` array |Add the permissions the user needs to `auth.ai.permissions`. |`allowed: false` on specific endpoints only |Missing the specific permission |Decode token, check the `auth.ai.permissions` array against the table above. -|Token silently rejected, no decoded error |RS256 signature |Re-sign with HS256. |`aud` claim type mismatch |`aud` issued as array instead of string |Some JWT libraries default to array `aud`. Force string. |Editor shows an error, and the browser console logs `TinyMCE AI Error:` with the cause, for example `Invalid JWT token provider result` or `Invalid JWT token payload` |Token endpoint returned `token` as a nested object, or returned a token without the required claims |Open browser devtools → Network → inspect the response from `/api/ai-token`. |=== diff --git a/modules/ROOT/pages/tinymceai-on-premises-mcp.adoc b/modules/ROOT/pages/tinymceai-on-premises-mcp.adoc index 8a511223bc..a737fe252b 100644 --- a/modules/ROOT/pages/tinymceai-on-premises-mcp.adoc +++ b/modules/ROOT/pages/tinymceai-on-premises-mcp.adoc @@ -179,7 +179,7 @@ The `headers` field sends a fixed set of HTTP headers with every request to the }' ---- -If the MCP server requires per-user context without OAuth, encode identity in the conversation prompt or in a header that the MCP server resolves to a per-user identity on its own side. +If the MCP server requires per-user context without OAuth, encode identity in the conversation prompt or in a header that the MCP server resolves to a per-user identity on its own side. Custom integrations built on the REST API can also pass per-request data to one MCP server, or to one of its tools, with an `mcp-tool-context` message content part. See https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Messages/operation/createMessage[Send a message] in the API reference. [[mcp-oauth]] === OAuth 2.0 authentication @@ -294,7 +294,7 @@ A typical integration requires four proxy routes: [[mcp-oauth-endpoints]] ==== REST endpoints -All endpoints are authenticated with the same JWT used for other AI service endpoints. The acting user is identified by the token; each user has an independent connection state per MCP server. +All endpoints are authenticated with the same JWT used for other AI service endpoints, and the token needs the `ai:conversations:read` and `ai:conversations:write` permissions. The acting user is identified by the token; each user has an independent connection state per MCP server. For requests, responses, and errors, see https://tinymceai.api.tiny.cloud/v1/docs#tag/MCP-OAuth[MCP OAuth] in the API reference. [cols="1,2,3",options="header"] |=== @@ -621,7 +621,8 @@ Custom streaming UI integrations can use the following Server-Sent Events (SSE) [cols="1,3",options="header"] |=== |Event name |Description -|`mcp-tool-result` |Emitted when an MCP tool call completes. Contains the tool result. There is no pre-call event; clients receive no signal until the tool call finishes. +|`mcp-tool-result` |Emitted when an MCP tool call completes. Contains the tool result. There is no pre-call event. +|`mcp-tool-notification` |Emitted when an MCP tool sends a notification while the call runs. Contains the tool name, the severity level, and the notification data. |`web-search` |Sent when a web search runs. The payload is an empty object, and the event is also sent when the search back end fails (see <>). |`source` |Emitted with source citations from the model response. |=== @@ -684,6 +685,9 @@ For production clusters, the MCP server Deployments should have dedicated resour |`422 web-resource-download-error` from the web-resources endpoint |This single error code covers multiple failure modes: the scrape endpoint returned 5xx, returned non-JSON, returned an empty `data` field, or returned an unsupported `type` (anything other than `text/html` or `text/markdown`). Check AI service container logs for the underlying cause. +|`504 web-resource-download-timeout` from the web-resources endpoint +|The scrape endpoint did not respond in time. Check that the scraper is reachable from the AI service and the `WEBRESOURCES_REQUEST_TIMEOUT` value. For the other errors of this endpoint, see https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Web-Resources/operation/downloadWebResources[Download a web resource] in the API reference. + |`mcp-oauth-invalid-state` error from the `complete` endpoint |The authorization session expired. Sessions are valid for ten minutes after calling `initialize`. Restart the flow from `POST /v1/mcp/oauth/\{serverName}/initialize`. diff --git a/modules/ROOT/pages/tinymceai-on-premises-production.adoc b/modules/ROOT/pages/tinymceai-on-premises-production.adoc index 4d3a7900be..f599f86367 100644 --- a/modules/ROOT/pages/tinymceai-on-premises-production.adoc +++ b/modules/ROOT/pages/tinymceai-on-premises-production.adoc @@ -620,7 +620,7 @@ TIP: Inspect the first few entries with `docker logs ai-service --tail 5 | jq .` [cols="1,1,1,3",options="header"] |=== |Variable |Required |Default |Description -|`LLM_TELEMETRY_ENABLED` |No |`false` |Records AI spans: models, tools, token usage, and the prompt and response of each call, with the reasoning text when the model reasons. Without it, the OTLP export carries only HTTP and database spans, and Langfuse receives no data. AI spans contain user documents, so choose the tracing back end and its retention period with that in mind. +|`LLM_TELEMETRY_ENABLED` |No |`true` in image version 1.3.0 and later; `false` in earlier versions |Records AI spans: models, tools, token usage, and the prompt and response of each call, with the reasoning text when the model reasons. The same records feed <>. Set to `false` to stop recording AI requests: the OTLP export then carries only HTTP and database spans, and Langfuse receives no data. AI spans contain user documents, so choose the tracing back end and its retention period with that in mind. |`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` |Yes (for OTLP export) |- |OpenTelemetry Protocol (OTLP) endpoint URL |`OTEL_TRACES_SAMPLER_ARG` |No |`1.0` |Sampling rate (0.0 to 1.0) |`OTEL_DEBUG` |No |- |Verbose OTLP diagnostic logging @@ -649,12 +649,23 @@ Langfuse provides AI-specific observability: token usage, latency per LLM call, |`LANGFUSE_DEBUG` |No |- |Verbose Langfuse logging |=== -Langfuse also requires `LLM_TELEMETRY_ENABLED=true`. The Langfuse export does not need `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`: the service sends spans to Langfuse directly. +Langfuse also requires `LLM_TELEMETRY_ENABLED=true`, the default in image version 1.3.0 and later. The Langfuse export does not need `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`: the service sends spans to Langfuse directly. When the other options come from a configuration file, pass the `OTEL_` and `LANGFUSE_` variables as environment variables. See xref:tinymceai-on-premises-reference.adoc#configuration-file[Configuration file]. OpenTelemetry and Langfuse can run at the same time. The service emits to both without conflict. +[[ai-diagnostics]] +=== AI Diagnostics + +In image version 1.3.0 and later, the Management Panel includes an AI Diagnostics view. It shows the traces and turns of each AI request: chat messages, actions, reviews, and Document Processing requests, with the prompt, the response, the model, token usage, and timing. Use it to investigate failed or unexpected responses without running a separate tracing back end. + +To open it, sign in to the Management Panel at `/panel/`, open the environment, and select the *AI diagnostics* tab. The view can export the records for a time range, a user, or a conversation. When escalating an issue, send the exported file to the Tiny Customer Success team. + +AI Diagnostics is on by default. The records are stored in the service database and removed after 30 days. Set `LLM_TELEMETRY_ENABLED` to `false` and restart the service to stop recording. + +IMPORTANT: The records contain prompts, responses, and document content. Anyone who can sign in to the Management Panel can read them. + === Distributed logging For production multi-instance deployments, ship container logs to the existing log aggregator. The metric logs produced by the `ENABLE_METRIC_LOGS` option are already structured JSON and parse cleanly in any pipeline. Refer to the platform documentation for the appropriate log driver or DaemonSet configuration (CloudWatch, Fluent Bit, Promtail, Filebeat, or the Docker fluentd log driver). diff --git a/modules/ROOT/pages/tinymceai-on-premises-providers.adoc b/modules/ROOT/pages/tinymceai-on-premises-providers.adoc index b5ccb477c1..818ceadd3f 100644 --- a/modules/ROOT/pages/tinymceai-on-premises-providers.adoc +++ b/modules/ROOT/pages/tinymceai-on-premises-providers.adoc @@ -921,6 +921,7 @@ a|[source,json] "id": "meta-llama/Llama-3.1-8B-Instruct", "provider": "vllm", "name": "Llama 3.1 8B (vLLM)", + "description": "Self-hosted Llama model served by vLLM", "features": ["conversations", "reviews", "actions"] } ---- @@ -941,6 +942,7 @@ a|[source,json] "id": "lmstudio-community/Meta-Llama-3.1-8B-Instruct-GGUF", "provider": "lmstudio", "name": "Llama 3.1 8B (LM Studio)", + "description": "Local Llama model served by LM Studio", "features": ["conversations", "reviews", "actions"] } ---- @@ -948,21 +950,16 @@ a|[source,json] === Verify -After starting the AI service with an openai-compatible provider configured, confirm it can reach the runtime: +The AI service does not expose an OpenAI-compatible endpoint of its own. It appends `/chat/completions` to the `baseUrl` of the provider. To verify the setup, first confirm that the runtime answers at that path prefix. For the Ollama example, run on the host: [source,bash] ---- -curl -s http://localhost:8000/v1/chat/completions \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer " \ - -d '{ - "model": "qwen3:0.6b", - "messages": [{"role":"user","content":"Say hello in five words."}], - "stream": false - }' +curl -s http://localhost:11434/v1/models ---- -A successful response confirms the AI service can forward requests to the local runtime. +The response lists the models that the runtime serves. Each `id` in `MODELS` must match one of them. + +Then open the editor, select the local model in Chat, and send a message. If the reply fails, the AI service log contains the URL that the service called on the runtime. A `404` response from that URL usually means that the `baseUrl` is missing the `/v1` path prefix. @@ -1020,7 +1017,7 @@ A `MODELS` array routes individual models to specific providers using the `provi ---- ==== -This wires conversations to OpenAI, reviews to Bedrock-hosted Claude, and quick actions to a local Ollama model. The {productname} editor will pick the appropriate provider for each feature based on which models declare which `features`. +This wires conversations to OpenAI, reviews to Bedrock-hosted Claude, and quick actions to a local Ollama model. The AI service picks the appropriate provider for each feature based on which models declare which `features`. See <>. A `MODELS` entry with a `provider` value that does not exist in `PROVIDERS` stops the service at startup with `[FATAL] Following models have invalid provider:` followed by the affected model IDs. Check the spelling of each `provider` field against the keys in `PROVIDERS`. See xref:tinymceai-on-premises-troubleshooting.adoc[Troubleshooting] for additional debugging steps. diff --git a/modules/ROOT/pages/tinymceai-on-premises-reference.adoc b/modules/ROOT/pages/tinymceai-on-premises-reference.adoc index 0bbf0983b2..ea661b361d 100644 --- a/modules/ROOT/pages/tinymceai-on-premises-reference.adoc +++ b/modules/ROOT/pages/tinymceai-on-premises-reference.adoc @@ -31,13 +31,13 @@ Alphabetized. Required-ness is marked relative to a minimum working deployment. |`GOOGLE_VERTEX_LOCATION` |No |- |Alternative to the `location` field of a Vertex AI provider. See xref:tinymceai-on-premises-providers.adoc#google-vertex-ai[Google Vertex AI]. |`GOOGLE_VERTEX_PROJECT` |No |- |Alternative to the `project` field of a Vertex AI provider. See xref:tinymceai-on-premises-providers.adoc#google-vertex-ai[Google Vertex AI]. |`GUARDRAILS` |No |- |JSON object; per-operation guardrail configuration. Guardrails are off by default. See xref:tinymceai-on-premises-guardrails.adoc[Guardrails]. -|`HOOKS` |No |- |JSON object; hook endpoint, enabled hook events, and signing configuration. See xref:tinymceai-on-premises-hooks.adoc[Hooks]. +|`HOOKS` |No |- |JSON object; hook endpoint, enabled hook events, and signing configuration. Image version 1.3.0 and later. See xref:tinymceai-on-premises-hooks.adoc[Hooks]. |`LANGFUSE_BASE_URL` |No |`https://cloud.langfuse.com` |Self-hosted Langfuse URL. |`LANGFUSE_DEBUG` |No |- |Verbose Langfuse logging. |`LANGFUSE_PUBLIC_KEY` |If using Langfuse |- |Langfuse public key. |`LANGFUSE_SECRET_KEY` |If using Langfuse |- |Langfuse secret key. |`LICENSE_KEY` |Yes |- |AI service license key (long string from Tiny). The same key is shared across all replicas of a deployment — no per-pod licensing is required. -|`LLM_TELEMETRY_ENABLED` |No |`false` |Records spans for AI operations. See xref:tinymceai-on-premises-production.adoc#observability[Observability]. +|`LLM_TELEMETRY_ENABLED` |No |`true` in image version 1.3.0 and later; `false` in earlier versions |Records spans for AI operations, including the records shown in AI Diagnostics. Set to `false` to stop recording AI requests. See xref:tinymceai-on-premises-production.adoc#observability[Observability]. |`LLM_TIMEOUT_MS` |No |180000 |Per-request large language model (LLM) timeout in ms. Raise for large self-hosted models. |`LOG_LEVEL` |No |`40` |Lowest log level written to the container output. See xref:tinymceai-on-premises-troubleshooting.adoc#log-levels[Log levels]. |`MCP_OAUTH_CALLBACK_URL` |If using MCP OAuth |- |URL of the OAuth callback page hosted by the integrating web application. Used as the OAuth `redirect_uri` for all OAuth-enabled MCP servers (unless overridden per server). See xref:tinymceai-on-premises-mcp.adoc#mcp-oauth[OAuth 2.0 authentication]. @@ -169,7 +169,7 @@ For PostgreSQL, change `DATABASE_DRIVER` to `'postgres'` and add `-e DATABASE_SC |GET |`/docs/` |None |Redirects (HTTP 301) to `/v1/api/docs`. |GET |`/v1/api/docs` |None |ReDoc-rendered API documentation. |GET |`/v1/api/doc.json` |None |OpenAPI 3 JSON spec. -|GET |`/panel/` |Management secret (login form) |Management Panel UI. Sign in with `ENVIRONMENTS_MANAGEMENT_SECRET_KEY` through the browser login form. +|GET |`/panel/` |Management secret (login form) |Management Panel UI. Sign in with `ENVIRONMENTS_MANAGEMENT_SECRET_KEY` through the browser login form. In image version 1.3.0 and later, the panel includes the xref:tinymceai-on-premises-production.adoc#ai-diagnostics[AI Diagnostics] view. |GET |`/v1/models/1` |JWT |List available models for the current token. The compatibility version literal `1` is the only accepted value. Other values, such as `v1`, `v2`, and `latest`, return `400 Bad Request`. |POST |`/v1/conversations` |JWT |Create a conversation. Body *must* include client-supplied `id`. |GET |`/v1/conversations` |JWT |List conversations for the current `sub`. @@ -194,7 +194,7 @@ For PostgreSQL, change `DATABASE_DRIVER` to `'postgres'` and add `-e DATABASE_SC |GET, POST, PUT, DELETE |`/v1/admin/mcp-servers` and `/v1/admin/mcp-servers/\{mcpServerName}` |JWT with `ai:admin` |List, register, read, update, and remove the MCP servers of the environment in the token. Image version 1.2.0 and later. See xref:tinymceai-on-premises-mcp.adoc#mcp-admin-api[MCP server admin API], and for each operation, see https://tinymceai.api.tiny.cloud/v1/docs#tag/MCP-Server-Admin[MCP Server Admin] in the API reference. |=== -NOTE: The OAuth endpoints are available only when at least one MCP server has an `oauth` block configured. The interactive API documentation at `/v1/api/docs` may not include these endpoints; they are documented in the xref:tinymceai-on-premises-mcp.adoc#mcp-oauth[MCP OAuth section]. +NOTE: The OAuth endpoints work only for MCP servers that have an `oauth` block configured. For a server without one, the authorization request returns HTTP `422`. See xref:tinymceai-on-premises-mcp.adoc#mcp-oauth[OAuth 2.0 authentication], and for each operation, see https://tinymceai.api.tiny.cloud/v1/docs#tag/MCP-OAuth[MCP OAuth] in the API reference. NOTE: Environment management (create, read, update, delete) is handled through the Management Panel UI at `/panel/`. @@ -249,7 +249,7 @@ The action and review endpoints also return SSE streams, with their own events. == Error code reference -Error codes returned in HTTP 4xx responses and inside SSE `event: error` payloads. +Error codes returned in HTTP 4xx and 5xx responses and inside SSE `event: error` payloads. Every error response carries a `+traceId+`. See xref:tinymceai-on-premises-troubleshooting.adoc#tracing-a-failed-request[Tracing a failed request]. @@ -264,7 +264,7 @@ Every error response carries a `+traceId+`. See xref:tinymceai-on-premises-troub |`invalid-request-data` |Input validator |Field validation failed (most commonly the 100,000 char prompt cap) |Fix the request body. See error message |`environment-not-found` |AI runtime |Same as `Environment not found`. The editor displays this error as `Invalid API key provided in JWT token (aud) claim`. |Recreate through Panel UI |`conversation in use` |Conversation runtime |Stream-abort left stale state |Start a new conversation -|`conversation does not exist` |Conversation runtime |Follow-up to `conversation in use` |Start a new conversation +|`conversation-not-found` (HTTP 404) |Conversation runtime |The conversation does not exist, for example as a follow-up to `conversation in use` |Start a new conversation |`NoValidApiKeysFoundError` (HTTP 500) |Bedrock / Vertex adapter |No credentials that the service can use |See xref:tinymceai-on-premises-providers.adoc#aws-bedrock[AWS Bedrock] or xref:tinymceai-on-premises-providers.adoc#google-vertex-ai[Google Vertex AI] |`AccessDeniedException` |Bedrock |Missing model access or IAM permissions |Enable Bedrock model access; attach the IAM policy from xref:tinymceai-on-premises-providers.adoc[LLM providers] |`INVALID_PAYMENT_INSTRUMENT` |Bedrock |Anthropic on Bedrock without Marketplace subscription |Subscribe through AWS Marketplace @@ -278,8 +278,8 @@ Every error response carries a `+traceId+`. See xref:tinymceai-on-premises-troub |License error with a reason |License check |In image version 1.2.0 and later, a license error in an API response states its reason |Act on the stated reason, or contact Tiny support with it |`content-rejected` (HTTP 422) |Guardrails |A guardrail classified the content as an attack, such as prompt injection, or the content matched a blocklist phrase |Review the content, or adjust the guardrail configuration. See xref:tinymceai-on-premises-guardrails.adoc[Guardrails] |`unsafe-content-detected` (HTTP 422) |Content moderation |The moderation provider flagged the prompt, an image uploaded to a conversation, or a file uploaded to the context library. `data.flaggedCategories` lists the categories |Change the content, or adjust the moderation configuration. See xref:tinymceai-on-premises-moderation.adoc[Content moderation] -|`hook-failed` (HTTP 502) |Hooks |The configured hook endpoint did not complete successfully |Check the hook endpoint logs using the `requestId` value. See xref:tinymceai-on-premises-hooks.adoc[Hooks] -|`hook-timeout` (HTTP 504) |Hooks |The configured hook endpoint did not respond in time |Check the hook endpoint availability and the hook timeout settings. See xref:tinymceai-on-premises-hooks.adoc[Hooks] +|`hook-failed` (HTTP 502) |Hooks (image version 1.3.0 and later) |The configured hook endpoint did not complete successfully |Check the hook endpoint logs using the `requestId` value. See xref:tinymceai-on-premises-hooks.adoc[Hooks] +|`hook-timeout` (HTTP 504) |Hooks (image version 1.3.0 and later) |The configured hook endpoint did not respond in time |Check the hook endpoint availability and the hook timeout settings. See xref:tinymceai-on-premises-hooks.adoc[Hooks] |=== == Known limits @@ -294,7 +294,7 @@ Every error response carries a `+traceId+`. See xref:tinymceai-on-premises-troub |Built-in rate limiting |None |Front the service with nginx `limit_req` or ALB rate-limit rules. See xref:tinymceai-on-premises-production.adoc#rate-limiting[Rate limiting]. |File support (OpenAI-compatible providers) |Images only (`image/*`) |PDFs, text, and Office files are not forwarded to OpenAI-compatible providers. Use a non-OpenAI-compatible provider for non-image file attachments. |MCP tool availability |Conversations, and Document Processing in image version 1.1.0 and later |MCP tools are not available in reviews or quick actions. Document Processing skips OAuth-enabled servers. -|MCP authentication |Static token or OAuth 2.0, configured independently for each server |Static tokens use the `headers` field (shared across all users, fixed at deploy time). Per-user authentication is supported through OAuth 2.0 (Authorization Code with PKCE). See xref:tinymceai-on-premises-mcp.adoc#mcp-oauth[OAuth 2.0 authentication]. +|MCP authentication |Static token or OAuth 2.0, configured independently for each server |Static tokens use the `headers` field (shared across all users). They are fixed at deploy time in `MCP_SERVERS`, or, in image version 1.2.0 and later, set for each environment through the xref:tinymceai-on-premises-mcp.adoc#mcp-admin-api[MCP server admin API]. Per-user authentication is supported through OAuth 2.0 (Authorization Code with PKCE). See xref:tinymceai-on-premises-mcp.adoc#mcp-oauth[OAuth 2.0 authentication]. |PostgreSQL default schema |`cs-on-premises` (with hyphen) |Pre-create with `CREATE SCHEMA "cs-on-premises";` or set `DATABASE_SCHEMA=public`. |`/v1/models/\{compatibilityVersion}` |Only accepts `1` |Values such as `v1`, `v2`, or `latest` return 400. |Environment creation through raw API |Not supported |Always create environments through the Management Panel UI. diff --git a/modules/ROOT/pages/tinymceai-on-premises-troubleshooting.adoc b/modules/ROOT/pages/tinymceai-on-premises-troubleshooting.adoc index 777b3fe341..40536b7376 100644 --- a/modules/ROOT/pages/tinymceai-on-premises-troubleshooting.adoc +++ b/modules/ROOT/pages/tinymceai-on-premises-troubleshooting.adoc @@ -5,7 +5,7 @@ :keywords: AI, on-premises, troubleshooting, errors, debugging, diagnostics, JWT, container, LLM :pluginname: TinyMCE AI -Match the symptom to the fix below. If the symptom does not fit any section, escalate to link:{supporturl}/[{supportname}] with the output of `docker logs ai-service --tail 200` and a redacted copy of the `PROVIDERS` value. +Match the symptom to the fix below. If the symptom does not fit any section, escalate to link:{supporturl}/[{supportname}] with the output of `docker logs ai-service --tail 200` and a redacted copy of the `PROVIDERS` value. In image version 1.3.0 and later, also attach an export from xref:tinymceai-on-premises-production.adoc#ai-diagnostics[AI Diagnostics], which shows the prompt, response, and model of each failed AI request. == Quick triage @@ -224,7 +224,7 @@ Confirm `/health` is OK and a direct `curl` to `/v1/conversations` works before |Symptom |Fix |No AI buttons in the toolbar -|Ensure {productname} 8{plus} is loaded, `plugins: 'tinymceai'` is set, and the toolbar string includes `tinymceai`. Verify the API key has the AI feature enabled. +|Ensure {productname} 8{plus} is loaded, `plugins: 'tinymceai'` is set, and the toolbar string includes the {pluginname} toolbar buttons, for example `tinymceai-chat tinymceai-review tinymceai-quickactions`. See xref:tinymceai.adoc#toolbar-buttons[Toolbar buttons]. Verify the API key has the AI feature enabled. |Token fetch returns 401 |The token endpoint's own authentication middleware is rejecting the request. Check session cookies, Cross-Origin Resource Sharing (CORS) credentials, and bearer tokens in the browser network tab. diff --git a/modules/ROOT/pages/tinymceai-on-premises.adoc b/modules/ROOT/pages/tinymceai-on-premises.adoc index dee7dde5a8..745d4fe0d1 100644 --- a/modules/ROOT/pages/tinymceai-on-premises.adoc +++ b/modules/ROOT/pages/tinymceai-on-premises.adoc @@ -79,7 +79,7 @@ The shared secret (API Secret) exists only in the application back end (token en |Use additional files as context for AI conversations. Storage options include database, filesystem, Amazon S3, or Azure Blob Storage. |Observability -|Structured request logs, OpenTelemetry, and Langfuse. All three run as independent simultaneous pipelines. +|Structured request logs, OpenTelemetry, and Langfuse. All three run as independent simultaneous pipelines. In image version 1.3.0 and later, the Management Panel also shows recorded AI requests in xref:tinymceai-on-premises-production.adoc#ai-diagnostics[AI Diagnostics]. |Horizontal scaling |The service is stateless; add replicas behind a load balancer without shared local state. diff --git a/modules/ROOT/pages/tinymceai-permissions.adoc b/modules/ROOT/pages/tinymceai-permissions.adoc index 34400a68f5..69083fe3cb 100644 --- a/modules/ROOT/pages/tinymceai-permissions.adoc +++ b/modules/ROOT/pages/tinymceai-permissions.adoc @@ -60,7 +60,7 @@ Permissions are an array of strings in the `+auth.ai.permissions+` claim of the |Permission |Description |`ai:admin` -|Grants full access to all {pluginname} features, models, and capabilities, and passes every permission check in the service. Required by the administration endpoints, such as the xref:tinymceai-usage.adoc[Usage API]. +|Grants full access to all {pluginname} features, models, and capabilities, and passes every permission check in the service. Required by the administration endpoints, such as the xref:tinymceai-usage.adoc[Usage API] and the https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Admin[Conversation Admin] operations, which list, get, and delete the conversations of any user. |=== [CAUTION] @@ -127,7 +127,7 @@ Conversation messages, custom actions, and custom reviews also require the permi |Access to all file types for context. |`ai:conversations:context:files:` -|Access to specific file formats (for example, `ai:conversations:context:files:pdf`, `ai:conversations:context:files:docx`). +|Access to specific file formats (for example, `ai:conversations:context:files:pdf`, `ai:conversations:context:files:docx`). Each upload format that the API accepts has its own permission: PDF, DOCX, PNG, JPEG, Markdown, HTML, and plain text. See https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Files/operation/uploadFile[Upload a file]. |`ai:conversations:context:urls` |Ability to use web URLs as context sources. diff --git a/modules/ROOT/pages/tinymceai-review.adoc b/modules/ROOT/pages/tinymceai-review.adoc index 5fa10d13e5..2c709a550c 100644 --- a/modules/ROOT/pages/tinymceai-review.adoc +++ b/modules/ROOT/pages/tinymceai-review.adoc @@ -34,7 +34,7 @@ To start using the Review feature, add `+tinymceai+` to the plugins configuratio See xref:tinymceai.adoc[Plugin Reference] for more information regarding installation and enabling AI features. -After picking one of the available reviews in the Review Mode tab, the AI will analyze the document and propose a series of suggestions: +After picking one of the available reviews in the Review sidebar, the AI will analyze the document and propose a series of suggestions: image::tinymceai/tinymce-ai-review-mode-suggestions-underlined-in-editor-content.png[{pluginname} Review suggestion in content,width=80%] @@ -48,6 +48,8 @@ Review suggestions can be individually skipped or applied by clicking the corres - Completing the review with the currently applied suggestions (and skipping the rest) - Aborting the review and exiting (with all applied changes reverted) +While a review has pending suggestions, switching to the Chat sidebar or running a Quick Action opens a confirmation dialog. If the user confirms, the plugin discards the pending suggestions and returns the editor to normal editing. If the user cancels, the plugin keeps the pending suggestions. For the same behavior across several editors, see xref:tinymceai-multi-editor.adoc#discarding-suggestions[Discarding pending suggestions]. + [[built-in-reviews]] == Built-in reviews @@ -80,7 +82,7 @@ a| |**Custom review** |— |xref:tinymceai-review.adoc#custom-review-choose-review[Custom review]: custom prompt and model; streams like other reviews. |✓ |✓ (custom review calls endpoint) -| |`+translate+` |Translate between languages with cultural adaptation. | |✓ +| |`+translate+` |Translate between languages with cultural adaptation. The request sets the target language in `+args.language+`. See https://tinymceai.api.tiny.cloud/v1/docs#tag/Reviews/operation/callSystemReview[Call a system review]. | |✓ |=== [NOTE] @@ -130,18 +132,20 @@ Integrators can also call the https://tinymceai.api.tiny.cloud/v1/docs#tag/Revie Users can also run custom reviews directly from the editor through the xref:tinymceai-review.adoc#custom-review-choose-review[Custom review] category in the Review sidebar. -Custom reviews require the `ai:reviews:custom` permission in the JWT token. See xref:tinymceai-permissions.adoc#reviews-permissions[Reviews permissions]. +Custom reviews require the `ai:reviews:custom` permission and the permission for the requested model in the JWT token. See xref:tinymceai-permissions.adoc#reviews-permissions[Reviews permissions] and xref:tinymceai-permissions.adoc#model-permissions[Model permissions]. [[reviews-streaming]] === Streaming responses -Reviews use Server-Sent Events (SSE) for real-time streaming results. See the xref:tinymceai-streaming.adoc[Streaming responses guide] for detailed implementation information. For the events and their payloads, see https://tinymceai.api.tiny.cloud/v1/docs#tag/Reviews/operation/callSystemReview[Call a system review] and https://tinymceai.api.tiny.cloud/v1/docs#tag/Reviews/operation/callCustomReview[Call a custom review] in the API reference. +Reviews use Server-Sent Events (SSE) for real-time streaming results. See the xref:tinymceai-streaming.adoc[Streaming responses guide] for detailed implementation information. A system review suggestion can come from a cache; its `+review-delta+` event then carries `+cached: true+`. For the events and their payloads, see https://tinymceai.api.tiny.cloud/v1/docs#tag/Reviews/operation/callSystemReview[Call a system review] and https://tinymceai.api.tiny.cloud/v1/docs#tag/Reviews/operation/callCustomReview[Call a custom review] in the API reference. [[reviews-api-reference]] === API reference The https://tinymceai.api.tiny.cloud/v1/docs#tag/Reviews[Reviews API] reference (interactive OpenAPI documentation) is the full source for endpoints, request and response schemas, authentication, system and custom review calls, worked examples, and streaming review responses. +To record user feedback on a result, https://tinymceai.api.tiny.cloud/v1/docs#tag/Reviews/operation/addSystemReviewRating[rate a system review call] or https://tinymceai.api.tiny.cloud/v1/docs#tag/Reviews/operation/addCustomReviewRating[rate a custom review call] with the `+callId+` from the `+review-metadata+` event of the review stream. + [[related-features]] == Related features diff --git a/modules/ROOT/pages/tinymceai-streaming.adoc b/modules/ROOT/pages/tinymceai-streaming.adoc index 3023a4ae52..b572eba2a2 100644 --- a/modules/ROOT/pages/tinymceai-streaming.adoc +++ b/modules/ROOT/pages/tinymceai-streaming.adoc @@ -42,6 +42,16 @@ data: Parsing this format correctly (including chunk boundaries, multi-line `+data:+` fields, and comments) is easy to get wrong in hand-written loops. For production code, use a maintained SSE parser such as the https://www.npmjs.com/package/eventsource-parser[`eventsource-parser`] package. +[[resumable-streams]] +=== Resumable reply streams + +Version 1.1 of the conversation message endpoints, under `+/v1.1+`, makes the reply stream more resilient. When replay is available for a reply, a client can: + +* https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Messages-V1.1/operation/resumeStream[Resume an interrupted reply] with `+GET /v1.1/conversations/{conversationId}/messages/{messageId}/stream+`. Set `+lastEventId+` to the ID of the last SSE event the client processed, or to `+0-0+` to replay the whole reply. +* https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Messages-V1.1/operation/cancelStream[Cancel a reply in progress] with `+DELETE+` on the same path. The content already generated is kept, and the stored message status becomes `+cancelled+`. + +Some replies stream without replay support. The reply still streams, but the resume and cancel operations are not available for it. For the request that starts a version 1.1 reply, see https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Messages-V1.1/operation/createMessageV2[Send a message (V1.1)]. + [[basic-implementation]] == Basic implementation @@ -96,6 +106,8 @@ while (true) { [[error-handling]] == Error handling +A request that the service rejects before the stream opens returns an HTTP error status with the JSON body described in xref:tinymceai-api-overview.adoc#error-responses[Error responses]. Errors after the stream opens arrive as an `+error+` event. + Always handle errors gracefully: [source,javascript] diff --git a/modules/ROOT/pages/tinymceai-usage.adoc b/modules/ROOT/pages/tinymceai-usage.adoc index a55d7363af..a0f0c31d1f 100644 --- a/modules/ROOT/pages/tinymceai-usage.adoc +++ b/modules/ROOT/pages/tinymceai-usage.adoc @@ -32,6 +32,6 @@ For the request and response fields and the error codes, see https://tinymceai.a * xref:tinymceai-permissions.adoc#admin-permissions[Admin permissions]: The `+ai:admin+` permission and how to handle administration tokens. * xref:tinymceai-jwt-authentication-intro.adoc[JWT authentication]: Token claims, including `+aud+` and `+sub+`. -* xref:tinymceai-limits.adoc[Limits]: Rate limits, context limits, and file limits. +* xref:tinymceai-limits.adoc[Limits]: Rate limits, context limits, and file limits, and the xref:tinymceai-limits.adoc#usage-limits[error returned when usage exceeds the limit] for the billing period. * xref:tinymceai-api-overview.adoc[API overview]: The features of the {pluginname} REST API and the conventions they share. * https://tinymceai.api.tiny.cloud/v1/docs#tag/Billing[Billing API]: Request and response schemas, and error codes. From f9e3208e7c7868c674dffab43feac17667809a55 Mon Sep 17 00:00:00 2001 From: Karl Kemister-Sheppard Date: Mon, 9 Nov 2026 09:08:22 +1000 Subject: [PATCH 2/9] TINYDOC-3686_V2: Nitpicks, corrections and improvements identified in audit. --- modules/ROOT/pages/tinymceai-actions.adoc | 4 +-- modules/ROOT/pages/tinymceai-chat.adoc | 8 +++--- .../pages/tinymceai-integration-options.adoc | 4 +-- .../tinymceai-jwt-authentication-intro.adoc | 6 +++-- modules/ROOT/pages/tinymceai-limits.adoc | 2 +- modules/ROOT/pages/tinymceai-models.adoc | 10 ++++--- .../ROOT/pages/tinymceai-multi-editor.adoc | 2 +- .../pages/tinymceai-on-premises-database.adoc | 2 +- .../tinymceai-on-premises-frameworks.adoc | 2 +- ...tinymceai-on-premises-getting-started.adoc | 2 +- .../pages/tinymceai-on-premises-hooks.adoc | 15 ++++++----- .../ROOT/pages/tinymceai-on-premises-jwt.adoc | 26 ++++++++++++------- .../ROOT/pages/tinymceai-on-premises-mcp.adoc | 12 +++++---- .../tinymceai-on-premises-moderation.adoc | 3 +-- .../tinymceai-on-premises-production.adoc | 10 ++++++- .../tinymceai-on-premises-providers.adoc | 10 ++++--- .../tinymceai-on-premises-reference.adoc | 8 +++--- ...tinymceai-on-premises-troubleshooting.adoc | 2 +- modules/ROOT/pages/tinymceai-on-premises.adoc | 5 +++- modules/ROOT/pages/tinymceai-permissions.adoc | 6 +++++ modules/ROOT/pages/tinymceai-review.adoc | 8 +++--- modules/ROOT/pages/tinymceai-streaming.adoc | 8 ++++-- modules/ROOT/pages/tinymceai.adoc | 4 +-- 23 files changed, 102 insertions(+), 57 deletions(-) diff --git a/modules/ROOT/pages/tinymceai-actions.adoc b/modules/ROOT/pages/tinymceai-actions.adoc index ab773fd2d3..149813856e 100644 --- a/modules/ROOT/pages/tinymceai-actions.adoc +++ b/modules/ROOT/pages/tinymceai-actions.adoc @@ -119,7 +119,7 @@ Custom actions can be added to the list, and default actions can be removed or r The following table lists built-in Quick Actions. * The **Editor** column is the label in the Quick Actions menu when that action is available in the editor. -* The **Menu or control ID** column lists values for `tinymceai_quickactions_menu`, `tinymceai_quickactions_chat_prompts`, `tinymceai_quickactions_change_tone_menu`, and the toolbar when adding individual controls (see xref:tinymceai-actions.adoc#configuring-quick-actions-menu[Configuring Quick Actions menu]). +* The **Menu or control ID** column lists values for `tinymceai_quickactions_menu`, `tinymceai_quickactions_chat_prompts`, `tinymceai_quickactions_change_tone_menu`, and the toolbar when adding individual controls (see xref:tinymceai-actions.adoc#configuring-quick-actions-menu[Configuring Quick Actions menu]). The `ai-quickactions-tone-*` identifiers are menu items only and cannot be added to the toolbar. * The **System `actionName` or quick-action prompt id** column is the service identifier. Preview actions use a system `actionName` with the xref:tinymceai-actions.adoc#actions-api[Actions API]. Chat actions use a quick-action prompt id and xref:tinymceai-chat.adoc[Chat] with a pre-filled prompt, not the system actions API. [cols="1,3,2,3,1,1",options="header"] @@ -261,7 +261,7 @@ Actions use streaming output with Server-Sent Events for real-time feedback as r Built-in Quick Actions—including identifiers, descriptions, and whether each command uses the system Actions API or Chat (Conversations API)—are summarized in xref:tinymceai-actions.adoc#quick-actions-reference-table[Default Actions]. -To run a system action, use https://tinymceai.api.tiny.cloud/v1/docs#tag/Actions/operation/callSystemAction[Call a system action] with an `+actionName+` from the rows that have a checkmark in the **API** column of the table above. System actions use built-in prompts, so the request needs no prompt or model. For the token scopes that each system action needs, see xref:tinymceai-permissions.adoc#actions-permissions[Actions permissions]. +To run a system action, use https://tinymceai.api.tiny.cloud/v1/docs#tag/Actions/operation/callSystemAction[Call a system action] with an `+actionName+` from the rows that have a checkmark in the **API** column of the table above. System actions use built-in prompts, so the request needs no prompt or model. The `+translate+` action also takes the target language in `+args.language+`. For the token scopes that each system action needs, see xref:tinymceai-permissions.adoc#actions-permissions[Actions permissions]. For endpoint details, request and response schemas, authentication, and streaming behavior for system `actionName` calls, see https://tinymceai.api.tiny.cloud/v1/docs#tag/Actions[Actions API]. diff --git a/modules/ROOT/pages/tinymceai-chat.adoc b/modules/ROOT/pages/tinymceai-chat.adoc index 54f24d694d..2d89eb4698 100644 --- a/modules/ROOT/pages/tinymceai-chat.adoc +++ b/modules/ROOT/pages/tinymceai-chat.adoc @@ -103,7 +103,7 @@ The model searches the web only when web search is enabled for the message. For Reasoning in Chat models turns on the ability to think through problems, draw logical conclusions, and make sense of complex information. It enables the model to analyze context, connect ideas, and produce well-structured, coherent answers beyond simple pattern matching. -Some models use reasoning automatically, while others may require manual activation. Whether the **Reasoning** toggle image:icons-premium/reasoning.svg[Reasoning icon,24px] below the prompt input needs to be toggled depends on the model and sometimes even how the prompt is worded. For models that support reasoning, use the toggle button to enable it. +The model reasons only when reasoning is enabled for the message, except for models that have xref:tinymceai-models.adoc#reasoning[reasoning always enabled]. For models that support reasoning, use the **Reasoning** toggle image:icons-premium/reasoning.svg[Reasoning icon,24px] below the prompt input to enable it. [[welcome-chat-actions]] == Customizing the welcome message @@ -246,7 +246,7 @@ image::tinymceai/tinymce-ai-chat-diff-mode-reject-suggestion-overlay.png[{plugin [[chat-history]] == Chat history -All past conversations appear in the Chat history. Click the image:icons/restore-draft.svg[Chat history icon,24px] button in the chat header to open the list. Click a conversation to reopen it, or use the menu on each entry to pin, rename, or delete it. Click **AI Chat** to return from the history view to the active conversation. +All past conversations appear in the Chat history. To show only the conversations for one document, set xref:tinymceai.adoc#content_id[`+content_id+`]. Click the image:icons/restore-draft.svg[Chat history icon,24px] button in the chat header to open the list. Click a conversation to reopen it, or use the menu on each entry to pin, rename, or delete it. Click **AI Chat** to return from the history view to the active conversation. The list shows pinned conversations under **Pinned**, and the other conversations under **History**. @@ -259,7 +259,7 @@ Any conversation from the chat history can be continued as long as the AI model [NOTE] ==== -After a full page load or new browser session, reopening Chat does not automatically reconnect the editor to pending suggestions from an older conversation. Open that conversation again from Chat history so pending suggestions are linked to the current editor session before accepting or dismissing them. +After a full page load or new browser session, reopening Chat does not automatically reconnect the editor to pending suggestions from an older conversation. Changes proposed in a conversation loaded from Chat history are shown as history and cannot be applied. Ask again in the current session to get new suggestions. ==== [[conversations-api]] @@ -293,7 +293,7 @@ Sending a message through the API takes three requests. The token needs the conv . https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversations/operation/createConversation[Create the conversation]. . Attach content: an https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Documents/operation/createDocument[HTML document], a https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Files/operation/uploadFile[file], or a https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Web-Resources/operation/downloadWebResources[web page]. File size limits are listed in xref:tinymceai-limits.adoc#file-limits[File limits]. -. https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Messages/operation/createMessage[Send the message]. The service streams the reply with Server-Sent Events (SSE). See xref:tinymceai-chat.adoc#conversations-streaming[Streaming responses]. +. https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Messages/operation/createMessage[Send the message]. The message lists each attached item by its ID in the `+content+` array. See the example in xref:tinymceai-models.adoc#model-selection[Model Selection]. The service streams the reply with Server-Sent Events (SSE). See xref:tinymceai-chat.adoc#conversations-streaming[Streaming responses]. [[conversations-api-capabilities]] === API capabilities diff --git a/modules/ROOT/pages/tinymceai-integration-options.adoc b/modules/ROOT/pages/tinymceai-integration-options.adoc index 82f9482293..dc2a4d98a7 100644 --- a/modules/ROOT/pages/tinymceai-integration-options.adoc +++ b/modules/ROOT/pages/tinymceai-integration-options.adoc @@ -5,7 +5,7 @@ :description_short: Integration options for TinyMCE AI :keywords: AI, integration, plugin, API, AI service, tinymceai -{pluginname} can be integrated with applications through two methods: +{pluginname} can be integrated with applications through the following methods: [cols=2*a] |=== @@ -26,7 +26,7 @@ Use the AI service API to build custom integrations and workflows. Suitable for [.lead] xref:tinymceai-on-premises.adoc[**On-Premises Deployment**] -Run the AI service as a self-hosted container within the host infrastructure, so document content, conversation history, and user data stay within the host network. Use it with the {pluginname} plugin or as a standalone service. Start with the xref:tinymceai-on-premises-getting-started.adoc[Getting started] guide. +Run the AI service as a self-hosted container within the host infrastructure, so document content, conversation history, and user data are stored within the host network. Data sent to the configured LLM provider is processed by that provider. Use it with the {pluginname} plugin or as a standalone service. Start with the xref:tinymceai-on-premises-getting-started.adoc[Getting started] guide. a| |=== diff --git a/modules/ROOT/pages/tinymceai-jwt-authentication-intro.adoc b/modules/ROOT/pages/tinymceai-jwt-authentication-intro.adoc index b09cf790eb..177d576f08 100644 --- a/modules/ROOT/pages/tinymceai-jwt-authentication-intro.adoc +++ b/modules/ROOT/pages/tinymceai-jwt-authentication-intro.adoc @@ -23,7 +23,7 @@ During a {cloudname} trial, a demo identity service is available for the {plugin [[trial-quick-start]] === Quick start -The following is the simplest way to use the demo identity service. Replace `\{apiKey}` with the trial API key from the link:{accountpageurl}[Customer Portal]. +The following is the simplest way to use the demo identity service. Replace `+no-api-key+` with the trial API key from the link:{accountpageurl}[Customer Portal]. [NOTE] ==== @@ -92,6 +92,8 @@ To authenticate users, {pluginname} uses tokens. The purpose of tokens is to inf *The token endpoint* is where {productname} makes a request to get the token. It is required to return the token only if the user proves their identity. It should be placed inside the system, not exposed as a public endpoint without proper authentication. +The plugin sends the token to the AI service in the `+Authorization+` header, as `+Bearer +`. Back-end code that calls the API directly sends the token the same way. A request without it fails with HTTP status `+401+` and the code `+missing-credentials+`. + The following diagram shows how {pluginname} uses tokens: image::JWT-flow.svg[JSON Web Token Call Flow,title="JSON Web Token Call Flow"] @@ -217,7 +219,7 @@ The signature is created by encoding the header and payload using Base64URL, the [[supported-algorithms]] === Supported Algorithms -{productname} does not support symmetrical encryption algorithms, such as `HS256`. {companyname} recommends using the `RS256` algorithm. The following algorithms are supported: +The {productname} AI service does not support symmetrical encryption algorithms, such as `HS256`. The xref:tinymceai-on-premises-jwt.adoc[on-premises service] uses `HS256`. {companyname} recommends using the `RS256` algorithm. The following algorithms are supported: * RS256 * RS384 diff --git a/modules/ROOT/pages/tinymceai-limits.adoc b/modules/ROOT/pages/tinymceai-limits.adoc index 5f0908abed..bcf6968f61 100644 --- a/modules/ROOT/pages/tinymceai-limits.adoc +++ b/modules/ROOT/pages/tinymceai-limits.adoc @@ -37,7 +37,7 @@ Context limits control how much content can be attached to conversations to ensu Supported attachment types include PDF, DOCX, PNG, JPEG, Markdown, HTML, and plain text. The API accepts files of up to 25 MB in a single upload to a conversation. Exact per-file, per-conversation, and PDF page limits also depend on the model in use. Read the `+limits+` object for that model from `GET /v1/models/\{version}` (see xref:tinymceai-models.adoc#verifying-model-limits-for-integration[Verifying limits for a configured model] and xref:tinymceai-models.adoc#model-information[Model Information]). For schema details, see the https://tinymceai.api.tiny.cloud/v1/docs#tag/Models[Models API] OpenAPI documentation. -The file picker in the {pluginname} plugin offers only the supported attachment types. The service enforces the file size and page count limits. A request over these limits fails with HTTP status `+413+`. See xref:tinymceai-api-overview.adoc#error-codes[Error codes]. +The file picker in the {pluginname} plugin offers only the supported attachment types. The service enforces the file size and page count limits. A file upload over these limits fails with HTTP status `+413+` and the code `+file-too-large+` or `+file-too-many-pages+`. Prompts and request bodies also have size limits. A conversation message, action, or review over them fails with HTTP status `+413+` and the code `+prompt-size-limits-exceeded+` or `+content-too-large+`. See xref:tinymceai-api-overview.adoc#error-codes[Error codes]. [[context-optimization-tips]] === Context Optimization Tips diff --git a/modules/ROOT/pages/tinymceai-models.adoc b/modules/ROOT/pages/tinymceai-models.adoc index f7950bcb47..a506f69ff1 100644 --- a/modules/ROOT/pages/tinymceai-models.adoc +++ b/modules/ROOT/pages/tinymceai-models.adoc @@ -238,6 +238,8 @@ The agent model (`agent-1`) automatically selects the best underlying model base When no model can process the request, the service returns a `+502 Bad Gateway+` error with the code `+no-available-models+`. Retry the request after a few minutes. +When the provider of the requested model does not respond, the service returns a `+502 Bad Gateway+` error with the code `+ai-provider-unavailable+`. Switch to another model or retry the request after a few minutes. + [[model-configuration]] === Model Configuration @@ -246,7 +248,7 @@ The JWT `auth.ai.permissions` array includes xref:tinymceai-permissions.adoc#mod Plugin configuration, API parameters, and per-feature options do not grant access to models that the JWT disallows; they only choose which *allowed* model to use in a given context: * **JWT model permissions**: Set `ai:models:*`, `ai:models:agent`, `ai:models::*`, or `ai:models::` as required. See xref:tinymceai-permissions.adoc#model-permissions[Model permissions] and xref:tinymceai-jwt-authentication-intro.adoc[JWT Authentication]. -* **Plugin configuration**: `tinymceai_default_model` sets the default model, and `tinymceai_allow_model_selection` controls whether end users can choose among allowed models in the UI. See xref:tinymceai.adoc#options-chat[Chat configuration options]. +* **Plugin configuration**: `tinymceai_default_model` sets the default model, and `tinymceai_allow_model_selection` controls whether end users can choose a model in the UI. The model selector lists every model that the models endpoint returns, and a model that the JWT does not allow fails when used. See xref:tinymceai.adoc#options-chat[Chat configuration options]. * **API requests**: The `model` field in request bodies selects the model for that call. See xref:tinymceai-models.adoc#api-examples[API Examples] below. * **Custom Quick Actions and similar**: Per-item options such as the `model` property on xref:tinymceai-actions.adoc#custom-actions[custom Quick Actions] select a model for that action; the value must be among the models allowed by the JWT. @@ -348,7 +350,7 @@ Web scraping extracts and processes content from web pages so the AI can analyze Per-model caps (context length, attachment sizes, PDF page totals, and similar) are returned in the `+limits+` object for each entry in `GET /v1/models/\{version}`. Those values are **the limits the service applies at runtime** and can differ by model. See xref:tinymceai-models.adoc#verifying-model-limits-for-integration[Verifying limits for a configured model] for how to match the integration’s model id to the correct `+items[]+` entry. -The sections below cover moderation, descriptions, and deprecation. Attachment limits are documented only under xref:tinymceai-models.adoc#file-processing-limits[File processing limits], using the live models API so values stay aligned with the service. +The sections below cover moderation, descriptions, and deprecation. Attachment limits are documented under xref:tinymceai-models.adoc#file-processing-limits[File processing limits], using the live models API so values stay aligned with the service. [[file-processing-limits]] === File Processing Limits @@ -407,6 +409,8 @@ To check for deprecated models programmatically, read the model list from `GET / The following examples show how to configure models when using the REST API directly. For plugin configuration, see xref:tinymceai-chat.adoc#model-selection-configuration[Chat model configuration]. +The examples post to an existing conversation and reference an existing document. To create them, see https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversations/operation/createConversation[Create a new conversation] and https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Documents/operation/createDocument[Create a document]. + [[model-selection]] === Model Selection @@ -523,7 +527,7 @@ Response (shape illustrated; field names and numeric limits follow the live serv * **`id`**: Model identifier for xref:tinymceai.adoc#tinymceai_default_model[`+tinymceai_default_model+`] and API `+model+` fields. * **`allowed`**: Whether the token's scopes allow the model. * **`recommended`**: Whether the service recommends the model. -* **`limits`**: Per-model numeric caps. Sizes are in bytes, and `+maxContextLength+` is a number of characters. The https://tinymceai.api.tiny.cloud/v1/docs#tag/Models/operation/getAiModels[Models API reference] defines each key. +* **`limits`**: Per-model numeric caps. Sizes are in bytes, and `+maxContextLength+` is a number of characters, counted as UTF-16 code units. The https://tinymceai.api.tiny.cloud/v1/docs#tag/Models/operation/getAiModels[Models API reference] defines each key. * **`capabilities`**: For `+webSearch+` and `+reasoning+`, whether the model supports the capability (`+enabled+`) and whether the token permits it (`+allowed+`). * **`+addition+`** and **`+removal+`** (optional): The dates the model becomes available and is removed. See xref:#model-deprecation[Model deprecation]. diff --git a/modules/ROOT/pages/tinymceai-multi-editor.adoc b/modules/ROOT/pages/tinymceai-multi-editor.adoc index 417a9fd0fd..3271d4be94 100644 --- a/modules/ROOT/pages/tinymceai-multi-editor.adoc +++ b/modules/ROOT/pages/tinymceai-multi-editor.adoc @@ -73,7 +73,7 @@ While the {pluginname} plugin previews changes from Chat or Quick Actions, each When any editor in the group has pending suggestions, the {pluginname} plugin asks for confirmation before it discards them and starts a different AI task. For example, the confirmation dialog appears when the user switches between the Chat sidebar and the Review sidebar, or runs a Quick Action while a review has pending suggestions. -If the user confirms, the plugin discards the pending suggestions in every editor of the group and returns each editor to normal editing. If the user cancels, the plugin keeps every preview and pending suggestion. +If the user confirms, the plugin discards the suggestions in every editor of the group, resets the changes already applied, and returns each editor to normal editing. If the user cancels, the plugin keeps every preview and pending suggestion. [[integration]] == Integration diff --git a/modules/ROOT/pages/tinymceai-on-premises-database.adoc b/modules/ROOT/pages/tinymceai-on-premises-database.adoc index 55540f77be..f0b20ddde7 100644 --- a/modules/ROOT/pages/tinymceai-on-premises-database.adoc +++ b/modules/ROOT/pages/tinymceai-on-premises-database.adoc @@ -7,7 +7,7 @@ This page covers the *data layer*: the SQL database, Redis, and file storage. These components must be running and accessible before the AI service container can start — the service connects to them on boot and will not proceed without them. -* *SQL database*: stores persistent data such as configurations, conversations, files, and documents. +* *SQL database*: stores persistent data such as configurations, conversations, file metadata, and documents. With `STORAGE_DRIVER` set to `database`, it also stores the uploaded files (see <>). In image version 1.3.0 and later, it also stores the records of xref:tinymceai-on-premises-production.adoc#ai-diagnostics[AI Diagnostics]. * *Redis*: caching and coordination (shared caches and in-progress SSE responses). Enables the AI service to remain stateless. * *File storage*: stores uploaded files and documents. diff --git a/modules/ROOT/pages/tinymceai-on-premises-frameworks.adoc b/modules/ROOT/pages/tinymceai-on-premises-frameworks.adoc index d61bf226df..bbf492b880 100644 --- a/modules/ROOT/pages/tinymceai-on-premises-frameworks.adoc +++ b/modules/ROOT/pages/tinymceai-on-premises-frameworks.adoc @@ -233,7 +233,7 @@ If the page and the token endpoint share an origin (or a parent domain), the bro fetch('/api/ai-token', { method: 'POST', credentials: 'include' }) ---- -For cross-origin token endpoints, the back end must respond with `Access-Control-Allow-Origin: ` (not `*`) and `Access-Control-Allow-Credentials: true`, and the session cookie must be set with `SameSite=None; Secure`. +For cross-origin token endpoints, the back end must respond with `Access-Control-Allow-Origin: ` (not `*`) and `Access-Control-Allow-Credentials: true`. When the token endpoint is on a different site, not only a different subdomain, the session cookie must also be set with `SameSite=None; Secure`. === Bearer header diff --git a/modules/ROOT/pages/tinymceai-on-premises-getting-started.adoc b/modules/ROOT/pages/tinymceai-on-premises-getting-started.adoc index 252c188b30..38c4a002b3 100644 --- a/modules/ROOT/pages/tinymceai-on-premises-getting-started.adoc +++ b/modules/ROOT/pages/tinymceai-on-premises-getting-started.adoc @@ -383,7 +383,7 @@ NOTE: Replace `'your-license-key'` in the `token-server.js` listing with the {pr npm install ---- -The {pluginname} plugin must be present in the {productname} plugins directory before starting the demo. Copy the `tinymceai` folder into `node_modules/tinymce/plugins/`, or use the xref:editor-important-options.adoc#external_plugins[`external_plugins`] option to load it from a separate path. +The {pluginname} plugin and the `licensekeymanager` plugin must be present in the {productname} plugins directory before starting the demo. With a commercial `license_key`, the editor disables itself when the `licensekeymanager` plugin is missing. Copy the `tinymceai` and `licensekeymanager` folders into `node_modules/tinymce/plugins/`, or use the xref:editor-important-options.adoc#external_plugins[`external_plugins`] option to load them from a separate path. For where to get the plugins, see xref:tinymceai.adoc#availability[Availability] and xref:npm-projects.adoc#install-premium-plugins[Install premium plugins from NPM]. [source,bash] ---- diff --git a/modules/ROOT/pages/tinymceai-on-premises-hooks.adoc b/modules/ROOT/pages/tinymceai-on-premises-hooks.adoc index a1260922c2..703f5ffef7 100644 --- a/modules/ROOT/pages/tinymceai-on-premises-hooks.adoc +++ b/modules/ROOT/pages/tinymceai-on-premises-hooks.adoc @@ -19,7 +19,7 @@ The `+HOOKS+` environment variable configures hooks on the AI service container. [[scope]] === Scope -* Hooks run for chat messages only. Quick actions, reviews, and Document Processing do not call hooks. +* Hooks run for chat messages only, including xref:tinymceai-actions.adoc#quick-actions-reference-table[Quick Actions that open in Chat] (*Explain*, *Summarize*, *Highlight key points*, and custom actions with `+type: 'chat'+`). Other quick actions, reviews, and Document Processing do not call hooks. * One event exists: `+turn.start+`. It fires after the user sends a chat message and before the AI service calls a model. * One endpoint and one shared secret serve the whole deployment. Every environment calls the same URL, and each request carries the `+environmentId+` of the turn. * Hooks run only for the events listed in `+enabled+`. When `+HOOKS+` is not set, no hooks run. @@ -535,6 +535,8 @@ A stated intent replaces the classification entirely. The AI service does not fi |Object with string keys. Merged into the metadata of the stored message, replacing client attributes with the same key. Not size-checked, and never sent to the model. |=== +Clients set message attributes in the `+attributes+` field of https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Messages/operation/createMessage[Send a message], and read the stored attributes back with https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Messages/operation/getMessages[Fetch conversation messages]. + A decision that exceeds a limit fails the turn. Keep instructions short regardless of the limit, because they enter the prompt on every turn that the hook sends them on. Only `+reply+` enters the conversation history. The AI service logs and traces the request and decision bodies, but does not store them as messages. See xref:tinymceai-on-premises-production.adoc#opentelemetry[OpenTelemetry]. @@ -550,7 +552,7 @@ Respond with `+content-type: application/json+` and the decision as the whole bo `+stream+`:: Respond with `+content-type: application/x-ndjson+` and write one JSON object per line, flushing each line. The AI service sends `+accept: application/x-ndjson+` in this mode. Any other response content type fails the turn. `+timeoutMs+` limits the whole exchange, and `+streamIdleTimeoutMs+` limits the wait for the response headers and each gap between lines. When the exchange fails partway, the progress lines and reply text already sent stay in the reply stream, followed by an `+error+` event. See <>. -Use `+json+` when the endpoint answers in a second or two. Use `+stream+` when it takes longer, or to stream progress lines to the client. +Use `+json+` when the endpoint answers in a second or two. Use `+stream+` when it takes longer, or to stream progress lines to a custom chat interface. [[stream-lines]] === Stream lines @@ -650,7 +652,7 @@ A hook can check every chat message against organization rules and refuse the me * Screen `+turn.prompt+`. A `+file+` or `+web-resource+` part carries no content, so to screen an attachment, read it through the API as described in <>. * When the rules call another service that is unavailable, do not respond with `+continue+`. Respond with `+halt+` and a refusal that the user can read, or with an error status, which fails the turn with the general chat error message. Both keep the check fail-closed. -* Hooks do not screen quick actions, reviews, or Document Processing. To apply the policy to every request from a group of users, grant only chat permissions in their tokens: +* Hooks screen every chat message, including Quick Actions that open in Chat. Other quick actions, reviews, and Document Processing do not call hooks. To apply the policy to every request from a group of users, grant only chat permissions in their tokens: [source,json] ---- @@ -660,14 +662,14 @@ A hook can check every chat message against organization rules and refuse the me "permissions": [ "ai:conversations:read", "ai:conversations:write", - "ai:models:openai:gpt-4.1" + "ai:models:agent" ] } } } ---- -Replace `+ai:models:openai:gpt-4.1+` with the model permissions for the deployment. See xref:tinymceai-on-premises-jwt.adoc#permissions-reference[Permissions reference]. Token permissions are the control; hiding a toolbar button in the editor does not enforce anything. +Replace `+ai:models:agent+` with the model permissions for the deployment. See xref:tinymceai-on-premises-jwt.adoc#permissions-reference[Permissions reference]. Token permissions are the control; hiding a toolbar button in the editor does not enforce anything. A hook does not replace xref:tinymceai-on-premises-moderation.adoc[content moderation]. A hook applies the integrator's own rules to chat messages only, and fails closed. Moderation checks requests against a fixed set of harm categories, and fails open. See xref:tinymceai-on-premises-moderation.adoc#what-moderation-checks[What moderation checks] and xref:tinymceai-on-premises-moderation.adoc#failure-behavior[Failure behavior]. @@ -715,6 +717,7 @@ The AI service calls the hook endpoint before xref:tinymceai-on-premises-moderat The {pluginname} plugin needs no configuration for hooks. A `+halt+` reply and a `+continue+` reply both appear in the chat as assistant messages. +* The {pluginname} plugin does not show `+progress+` lines: it ignores `+hook-progress+` events. * A custom chat interface built on the REST API can read `+hook-progress+` events and show each line. See xref:tinymceai-streaming.adoc[Streaming]. * To send custom front-end data in the hook request, attach `+delegation-context+` parts to messages through the conversation API. See https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Messages/operation/createMessage[Send a message] in the API reference. @@ -805,7 +808,7 @@ When the user stops the request before the endpoint responds, the AI service clo |In `+stream+` mode, chat turns fail after the endpoint responded with `+200+` |The stream failed after the response headers: it stalled for longer than `+streamIdleTimeoutMs+`, ran past `+timeoutMs+`, or ended with a decision outside the contract. Find the reason in the service log by the `+requestId+`. -|Every chat turn fails, while quick actions and reviews still work +|Every chat turn fails, including Quick Actions that open in Chat, while other quick actions and reviews still work |Hooks fail closed, and the hook endpoint is unavailable. Restore the endpoint, or set `+enabled+` to an empty array in `+HOOKS+` and restart the AI service to bypass hooks. |=== diff --git a/modules/ROOT/pages/tinymceai-on-premises-jwt.adoc b/modules/ROOT/pages/tinymceai-on-premises-jwt.adoc index da37e2e193..da1336b759 100644 --- a/modules/ROOT/pages/tinymceai-on-premises-jwt.adoc +++ b/modules/ROOT/pages/tinymceai-on-premises-jwt.adoc @@ -23,7 +23,7 @@ Do not follow the xref:tinymceai-jwt-authentication-intro.adoc[Cloud JWT guide] [.text-center] image::tinymceai-on-premises/jwt-authentication-fig-1.svg[alt="JWT token exchange sequence between user application back end and AI service with error branches",width=100%] -The shared secret (API Secret) never leaves the application back end. The editor only ever sees signed tokens, and the AI service only ever sees signed tokens; neither has direct access to the secret. +The shared secret (API Secret) never reaches the browser. The editor only ever sees signed tokens. @@ -105,7 +105,7 @@ The following table lists the permissions that most on-premises tokens use. For |`ai:conversations:websearch` |Enable the web search toggle in conversations. Without this permission, `GET /v1/models/1` reports `capabilities.webSearch.allowed: false` even when `WEBSEARCH_ENABLED=true` and `capabilities.webSearch: true` is set on the model. |`ai:conversations:reasoning` |Enable the reasoning toggle in conversations |`ai:models:agent` |Access the built-in agent model (model ID `agent-1`) -|`ai:models::` |Access a specific custom model configured through the `MODELS` env var +|`ai:models::` |Access one specific model, from the default configuration or from the `MODELS` env var |`ai:actions:system:*` |All system actions: `continue`, `fix-grammar`, `improve-writing`, `make-longer`, `make-shorter`, the `make-tone-*` actions, and `translate`. Chat actions, such as Summarize and Explain, use the conversation permissions instead. See xref:tinymceai-actions.adoc#default-actions[Default actions]. |`ai:reviews:system:*` |All built-in review features (correctness, clarity, readability, tone, and related checks) |`ai:contexts:` |Use one context from the xref:tinymceai-api-overview.adoc#contexts[context library]. `ai:contexts:*` covers every context. A context created with `autoApply` applies only to requests whose token covers it. For any other request, the service skips the context and returns no error. @@ -113,7 +113,7 @@ The following table lists the permissions that most on-premises tokens use. For === Model permission syntax -`ai:models::` selects a specific custom model. The parser is *not* a greedy colon-split; it understands that `` may itself contain colons and dots. +`ai:models::` selects a specific model. The parser is *not* a greedy colon-split; it understands that `` may itself contain colons and dots. Examples: @@ -153,7 +153,10 @@ For demos and admin-tier users, this is the standard grant: "ai:conversations:*", "ai:models:agent", "ai:actions:system:*", - "ai:reviews:system:*" + "ai:actions:custom", + "ai:reviews:system:*", + "ai:reviews:custom", + "ai:documents:process" ] ---- @@ -204,7 +207,7 @@ The service allows up to 60 seconds of clock skew on the `exp` claim. Keep the t == Production token endpoint examples -Each example reads `AI_ENV_ID` and `AI_API_SECRET` from environment variables, authenticates the user through the framework's session/auth layer, signs an HS256 token, and returns `{"token": "..."}` as JSON. The endpoint runs in the application back end; the AI service never sees the API Secret directly. +Each example reads `AI_ENV_ID` and `AI_API_SECRET` from environment variables, authenticates the user through the framework's session/auth layer, signs an HS256 token, and returns `{"token": "..."}` as JSON. The endpoint runs in the application back end. [cols="1,1",options="header"] |=== @@ -880,7 +883,8 @@ When debugging, start here. Most "auth failures" reflect wrong claim values rath |`Environment not found` |Environment is in `environments__environment` / `security__environment` but not in `ai_assistant_environments`, because the AI service is not attached to the environment |Recreate through Management Panel UI. |HTTP 500 error on every endpoint |`auth.ai.permissions` is not an array of strings |Must be ``string[]``. Not a single string. Not `useAllFeatures`. |HTTP 403 `no-permissions-defined` |The token has no `auth` claim, no `permissions` key, or an empty `permissions` array |Add the permissions the user needs to `auth.ai.permissions`. -|`allowed: false` on specific endpoints only |Missing the specific permission |Decode token, check the `auth.ai.permissions` array against the table above. +|HTTP 403 `missing-permissions`, or `allowed: false` for a model or capability in `GET /v1/models/1` |Missing the specific permission |Add the permissions listed in `data.missingPermissions` to the `auth.ai.permissions` array. See the table above. +|HTTP 401 `missing-credentials` |No `Authorization` header, or a scheme other than `Bearer` |Send the token as `Authorization: Bearer `. |`aud` claim type mismatch |`aud` issued as array instead of string |Some JWT libraries default to array `aud`. Force string. |Editor shows an error, and the browser console logs `TinyMCE AI Error:` with the cause, for example `Invalid JWT token provider result` or `Invalid JWT token payload` |Token endpoint returned `token` as a nested object, or returned a token without the required claims |Open browser devtools → Network → inspect the response from `/api/ai-token`. |=== @@ -889,7 +893,9 @@ When debugging, start here. Most "auth failures" reflect wrong claim values rath [source,bash] ---- -TOKEN=$(curl -s -X POST http://localhost:3000/api/ai-token | jq -r .token) +# The token endpoint requires a signed-in session. Pass the session cookie from a signed-in browser. +TOKEN=$(curl -s -X POST http://localhost:3000/api/ai-token \ + -H "Cookie: " | jq -r .token) curl -i https://ai.example.com/v1/conversations \ -H "Authorization: Bearer $TOKEN" \ @@ -969,8 +975,9 @@ function getPermissionsForPlan(plan) { case 'enterprise': return ['ai:conversations:*', 'ai:models:agent', 'ai:actions:system:*', 'ai:reviews:system:*']; case 'pro': - return ['ai:conversations:*', 'ai:actions:system:*']; + return ['ai:conversations:*', 'ai:models:agent', 'ai:actions:system:*']; case 'basic': + default: return ['ai:actions:system:*']; } } @@ -978,7 +985,8 @@ function getPermissionsForPlan(plan) { function getCustomerConfig(tenantId) { return { envId: process.env[`AI_ENV_ID_${tenantId}`], - apiSecret: process.env[`AI_API_SECRET_${tenantId}`] + apiSecret: process.env[`AI_API_SECRET_${tenantId}`], + plan: process.env[`AI_PLAN_${tenantId}`] }; } ---- diff --git a/modules/ROOT/pages/tinymceai-on-premises-mcp.adoc b/modules/ROOT/pages/tinymceai-on-premises-mcp.adoc index a737fe252b..9907ad988e 100644 --- a/modules/ROOT/pages/tinymceai-on-premises-mcp.adoc +++ b/modules/ROOT/pages/tinymceai-on-premises-mcp.adoc @@ -18,7 +18,7 @@ image::tinymceai-on-premises/mcp-web-integrations-architecture.svg[MCP and web i The following demo shows the editor experience that <> enables. The AI service backing the demo has an MCP server connected to a sample database of acquisition deals and company records. Choosing one of the suggested actions in the Chat sidebar prompts the model to call the MCP server's tools, then either fill in the document placeholders or answer in Chat. -The editor configuration shown in the *JS* tab applies to on-premises deployments without change. MCP servers are declared on the AI service through <>; the editor requires only the `+tinymceai+` plugin and a token provider. +On premises, the editor configuration shown in the *JS* tab also needs xref:tinymceai.adoc#tinymceai_service_url[`+tinymceai_service_url+`] set to the AI service URL, and xref:tinymceai.adoc#tinymceai_default_model[`+tinymceai_default_model+`] set to a model ID defined in `+MODELS+`. MCP servers are declared on the AI service through <>, not in the editor configuration. liveDemo::tinymceai-mcp[script_url_override="{tinymceai_mcp_live_demo_url}"] @@ -141,6 +141,8 @@ Servers defined in `MCP_SERVERS` and servers registered through the admin API sh * The admin API rejects a server name that `MCP_SERVERS` already uses. * When `MCP_SERVERS` later adds a name that was first registered through the admin API, the `MCP_SERVERS` entry replaces the registered server. +A server registered through the admin API with an `oauth` block must set `oauth.callbackUrl`. Changing the `url` or the `oauth` settings of a registered server, or deleting the server, revokes the OAuth tokens stored for it, and each user must authorize the server again. + Conversations and Document Processing requests use servers connected either way. [[mcp-resources]] @@ -179,7 +181,7 @@ The `headers` field sends a fixed set of HTTP headers with every request to the }' ---- -If the MCP server requires per-user context without OAuth, encode identity in the conversation prompt or in a header that the MCP server resolves to a per-user identity on its own side. Custom integrations built on the REST API can also pass per-request data to one MCP server, or to one of its tools, with an `mcp-tool-context` message content part. See https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Messages/operation/createMessage[Send a message] in the API reference. +The `headers` field is the same for every user, so it cannot carry a per-user identity. For per-user identity, use <>. Custom integrations built on the REST API can also pass per-request data to one MCP server, or to one of its tools, with an `mcp-tool-context` message content part. See https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Messages/operation/createMessage[Send a message] in the API reference. [[mcp-oauth]] === OAuth 2.0 authentication @@ -436,7 +438,7 @@ Web search requires three components configured together: |Set `WEBSEARCH_ENABLED='true'` and `WEBSEARCH_ENDPOINT` on the AI service container. Optionally set `WEBSEARCH_REQUEST_TIMEOUT` (default 10000ms) and `WEBSEARCH_HEADERS` for authenticated search backends. |MODELS entry -|The model's `MODELS` entry must include `capabilities.webSearch: true` (boolean) for the web search toggle to appear in the editor. See xref:tinymceai-on-premises-providers.adoc#models-required[MODELS configuration]. +|The model's `MODELS` entry must include `capabilities.webSearch: true` (boolean) for the web search toggle to be enabled in the editor. See xref:tinymceai-on-premises-providers.adoc#models-required[MODELS configuration]. |JWT permission |The JWT must include `ai:conversations:websearch` in the `auth.ai.permissions` array. See xref:tinymceai-on-premises-jwt.adoc#permissions-reference[JWT permissions]. Without this permission, the toggle remains grayed out even when the environment variables and MODELS entry are correct. @@ -661,11 +663,11 @@ For production clusters, the MCP server Deployments should have dedicated resour |=== |Symptom |Resolution -|Web search or web scraping features do not appear at all +|Web search or web scraping features do not work |`WEBSEARCH_ENABLED` and `WEBRESOURCES_ENABLED` both default to `false`. Set them to `true` in the AI service environment and provide the corresponding `_ENDPOINT` values. Without these flags enabled, the AI service disables all web integration features regardless of JWT permissions or MODELS configuration. |Web search toggle is grayed out in the editor -|The JWT is missing the `ai:conversations:websearch` permission. Add it to the `auth.ai.permissions` array in the token (or use the wildcard `ai:conversations:*`). See xref:tinymceai-on-premises-jwt.adoc#permissions-reference[JWT permissions]. +|The JWT is missing the `ai:conversations:websearch` permission. Add it to the `auth.ai.permissions` array in the token (or use the wildcard `ai:conversations:*`). See xref:tinymceai-on-premises-jwt.adoc#permissions-reference[JWT permissions]. The toggle is also grayed out when the selected model's `MODELS` entry does not include `capabilities.webSearch: true`. See xref:tinymceai-on-premises-providers.adoc#models-required[MODELS configuration]. |Web search is toggled on but the model never uses it |The per-message request body is missing `"capabilities": {"webSearch": {}}`. The {productname} editor sends this when the toggle is active. Custom integrations must include it in each request body. See <>. diff --git a/modules/ROOT/pages/tinymceai-on-premises-moderation.adoc b/modules/ROOT/pages/tinymceai-on-premises-moderation.adoc index 4005eb1f16..17c2f9be6b 100644 --- a/modules/ROOT/pages/tinymceai-on-premises-moderation.adoc +++ b/modules/ROOT/pages/tinymceai-on-premises-moderation.adoc @@ -295,8 +295,7 @@ Any response other than `+200+` lets the content through, including the `+401+` Moderation runs on the following input: * The prompt of each AI request: chat messages, quick actions, reviews, and Document Processing requests. -* Images, when a user uploads them to a conversation. -* Files, when they are uploaded to the context library. See xref:tinymceai-api-overview.adoc#contexts[Contexts] and https://tinymceai.api.tiny.cloud/v1/docs#tag/Context-Admin/operation/adminUploadContextFile[Upload a file to a context] in the API reference. +* Images, when they are uploaded to a conversation or to the context library. See xref:tinymceai-api-overview.adoc#contexts[Contexts] and https://tinymceai.api.tiny.cloud/v1/docs#tag/Context-Admin/operation/adminUploadContextFile[Upload a file to a context] in the API reference. * Prompts, when they are saved to the context library. * Text files from the context library, when an action, a review, or a Document Processing request attaches them. diff --git a/modules/ROOT/pages/tinymceai-on-premises-production.adoc b/modules/ROOT/pages/tinymceai-on-premises-production.adoc index f599f86367..c712044938 100644 --- a/modules/ROOT/pages/tinymceai-on-premises-production.adoc +++ b/modules/ROOT/pages/tinymceai-on-premises-production.adoc @@ -145,7 +145,7 @@ IMPORTANT: Pin to `mysql:8.0`. The `mysql:8` tag floats to the latest MySQL, whi == Kubernetes deployment -Deploy the AI service to Kubernetes in five steps: create a namespace, store secrets, apply the Deployment, expose as a Service, and verify. +Deploy the AI service to Kubernetes in five steps: create a namespace, store secrets, apply the Deployment, expose as a Service, and bootstrap the environment. === Step 1: Namespace and image pull secret @@ -521,6 +521,14 @@ The AI service requires outbound access to the following endpoints, depending on |Check prompts and uploaded images with the OpenAI moderation API before they reach a model |By default, when `PROVIDERS` includes an OpenAI provider and `MODERATION` does not configure a custom endpoint or turn the check off. See xref:tinymceai-on-premises-moderation.adoc[Content moderation]. +|Custom moderation endpoint +|Screen content with a moderation service hosted by the deployment +|Only when `MODERATION` uses the `custom` provider, in image version 1.1.0 and later. See xref:tinymceai-on-premises-moderation.adoc#custom-moderation-endpoint[Custom moderation endpoint]. + +|Hook endpoint +|Send chat turns to an endpoint hosted by the integrator before the model runs +|Only when `HOOKS` is configured, in image version 1.3.0 and later. See xref:tinymceai-on-premises-hooks.adoc[Hooks]. + |MCP servers |Call the tools of the connected Model Context Protocol (MCP) servers |Only when configured. See xref:tinymceai-on-premises-mcp.adoc#mcp-integration[MCP integration]. diff --git a/modules/ROOT/pages/tinymceai-on-premises-providers.adoc b/modules/ROOT/pages/tinymceai-on-premises-providers.adoc index 818ceadd3f..a006d99dd0 100644 --- a/modules/ROOT/pages/tinymceai-on-premises-providers.adoc +++ b/modules/ROOT/pages/tinymceai-on-premises-providers.adoc @@ -137,6 +137,8 @@ A full field reference for `MODELS` is at the end of this page. API key from https://platform.openai.com/api-keys[platform.openai.com]. The OpenAI provider comes with a default model list, so it works without an explicit `MODELS` definition, but defining `MODELS` is recommended for production (see <>). +NOTE: When `MODERATION` is not set, the AI service also uses the API key of the OpenAI provider in `PROVIDERS` for content moderation, and sends prompts and uploaded images to the OpenAI moderation API even when other providers serve the models. See xref:tinymceai-on-premises-moderation.adoc[Content moderation]. + .Configuration details [%collapsible] ==== @@ -782,7 +784,7 @@ IMPORTANT: *Region mismatch:* set `location` to a region that hosts the model. * Use this provider type for any runtime or aggregator that is not listed as a native provider above but exposes an OpenAI-compatible `/v1/chat/completions` endpoint — including Ollama, vLLM, LM Studio, OpenRouter, Together, Groq, and Fireworks. -The `baseUrl` *must* include the `/v1` suffix. +The `baseUrl` *must* include the OpenAI-compatible path prefix of the runtime, typically `/v1`. The AI service appends `/chat/completions` to the `baseUrl`. === Configuration @@ -802,7 +804,7 @@ The `baseUrl` *must* include the `/v1` suffix. |=== |Field |Required |Notes |`type` |Yes |Literal `"openai-compatible"` -|`baseUrl` |Yes |*Must include the `/v1` suffix.* Without it, every request fails with a misleading "Not Found" Server-Sent Events (SSE) error. +|`baseUrl` |Yes |*Must include the OpenAI-compatible path prefix of the runtime, typically `/v1`.* Without it, every request fails with a misleading "Not Found" Server-Sent Events (SSE) error. |`apiKeys` |No |Sent as `Authorization: Bearer `. Most local runtimes ignore it. |`headers` |No |Additional headers such as auth tokens or tenant IDs. |=== @@ -1017,7 +1019,7 @@ A `MODELS` array routes individual models to specific providers using the `provi ---- ==== -This wires conversations to OpenAI, reviews to Bedrock-hosted Claude, and quick actions to a local Ollama model. The AI service picks the appropriate provider for each feature based on which models declare which `features`. See <>. +This wires conversations to OpenAI, reviews to Bedrock-hosted Claude, and quick actions to a local Ollama model. The AI service picks the model for system reviews, system actions, and conversation title generation from the models that declare each feature in `features`. Chat messages, custom actions, and custom reviews use the model that the request names. See <>. A `MODELS` entry with a `provider` value that does not exist in `PROVIDERS` stops the service at startup with `[FATAL] Following models have invalid provider:` followed by the affected model IDs. Check the spelling of each `provider` field against the keys in `PROVIDERS`. See xref:tinymceai-on-premises-troubleshooting.adoc[Troubleshooting] for additional debugging steps. @@ -1197,7 +1199,7 @@ The same procedure works for `anthropic`, `google`, `azure`, and `openai-compati [cols=",,",options="header",] |=== |Symptom |Most likely cause |Section -|Editor shows "model unavailable" / `agent-1 allowed:false` |The token lacks `ai:models:agent` |<> +|Requests return HTTP 403 `missing-permissions` listing `ai:models:agent` / `agent-1 allowed:false` |The token lacks `ai:models:agent` |<> |`GET /v1/models/v1` returns 400 |Wrong compatibility version |<> |Bedrock returns `NoValidApiKeysFoundError` |No credentials that the service can use. In image versions earlier than 1.2.0, relying on the AWS default credential chain |Bedrock |Bedrock returns `AccessDeniedException` |Model access not enabled in console |Bedrock prerequisites diff --git a/modules/ROOT/pages/tinymceai-on-premises-reference.adoc b/modules/ROOT/pages/tinymceai-on-premises-reference.adoc index ea661b361d..1908a25664 100644 --- a/modules/ROOT/pages/tinymceai-on-premises-reference.adoc +++ b/modules/ROOT/pages/tinymceai-on-premises-reference.adoc @@ -187,6 +187,8 @@ For PostgreSQL, change `DATABASE_DRIVER` to `'postgres'` and add `-e DATABASE_SC |POST |`/v1/reviews/system/\{reviewName}/calls` |JWT |Run a built-in review, for example `+correctness+`. Returns an SSE stream. For the content format, see the https://tinymceai.api.tiny.cloud/v1/docs#tag/Reviews/operation/callSystemReview[API reference]. |POST |`/v1/actions/custom/calls` |JWT |Run a custom action with a prompt and a model. Returns an SSE stream. |POST |`/v1/reviews/custom/calls` |JWT |Run a custom review with a prompt and a model. Returns an SSE stream. +|POST |`/v1/documents/process` |JWT |Apply a prompt to an HTML document, or to several documents in image version 1.1.0 and later. See xref:tinymceai-document-processing.adoc[Document Processing]. +|POST |`/v1/documents/process/stream` |JWT |Streaming variant of `/v1/documents/process`. Returns an SSE stream. Image version 1.1.0 and later. See xref:tinymceai-document-processing.adoc#streaming[Streaming]. |GET |`/v1/mcp/oauth/status` |JWT |Connection status for all OAuth-enabled MCP servers. See xref:tinymceai-on-premises-mcp.adoc#mcp-oauth-endpoints[OAuth REST endpoints]. |POST |`/v1/mcp/oauth/\{serverName}/initialize` |JWT |Start the OAuth authorization flow. |POST |`/v1/mcp/oauth/\{serverName}/complete` |JWT |Complete the OAuth flow with the authorization code. @@ -249,7 +251,7 @@ The action and review endpoints also return SSE streams, with their own events. == Error code reference -Error codes returned in HTTP 4xx and 5xx responses and inside SSE `event: error` payloads. +Error codes returned in HTTP 4xx and 5xx responses and inside SSE `event: error` payloads. For every error code, see the https://tinymceai.api.tiny.cloud/v1/docs#section/Overview/Error-codes[Error codes] section of the API reference. Every error response carries a `+traceId+`. See xref:tinymceai-on-premises-troubleshooting.adoc#tracing-a-failed-request[Tracing a failed request]. @@ -264,7 +266,7 @@ Every error response carries a `+traceId+`. See xref:tinymceai-on-premises-troub |`invalid-request-data` |Input validator |Field validation failed (most commonly the 100,000 char prompt cap) |Fix the request body. See error message |`environment-not-found` |AI runtime |Same as `Environment not found`. The editor displays this error as `Invalid API key provided in JWT token (aud) claim`. |Recreate through Panel UI |`conversation in use` |Conversation runtime |Stream-abort left stale state |Start a new conversation -|`conversation-not-found` (HTTP 404) |Conversation runtime |The conversation does not exist, for example as a follow-up to `conversation in use` |Start a new conversation +|`conversation-not-found` (HTTP 404) |Conversation runtime |The conversation does not exist |Start a new conversation |`NoValidApiKeysFoundError` (HTTP 500) |Bedrock / Vertex adapter |No credentials that the service can use |See xref:tinymceai-on-premises-providers.adoc#aws-bedrock[AWS Bedrock] or xref:tinymceai-on-premises-providers.adoc#google-vertex-ai[Google Vertex AI] |`AccessDeniedException` |Bedrock |Missing model access or IAM permissions |Enable Bedrock model access; attach the IAM policy from xref:tinymceai-on-premises-providers.adoc[LLM providers] |`INVALID_PAYMENT_INSTRUMENT` |Bedrock |Anthropic on Bedrock without Marketplace subscription |Subscribe through AWS Marketplace @@ -301,5 +303,5 @@ Every error response carries a `+traceId+`. See xref:tinymceai-on-premises-troub |Bedrock credentials |Inline only, in image versions earlier than 1.2.0 |See xref:tinymceai-on-premises-providers.adoc#bedrock-newer-credentials[Assumed role and host credentials]. |Vertex credentials |Inline only, in image versions earlier than 1.2.0 |See xref:tinymceai-on-premises-providers.adoc#vertex-newer-credentials[Impersonation and host credentials]. |Azure `MODELS[].id` |Must equal deployment name |There is no separate `deploymentName` field. The ID is the deployment name. Start the deployment name with the ID of the OpenAI model it serves: the service reads that prefix to choose the request options for the model. -|OpenAI-compatible `baseUrl` |Must include `/v1` suffix |Omitting it produces a "Not Found" SSE error. +|OpenAI-compatible `baseUrl` |Must include the OpenAI-compatible path prefix of the runtime, typically `/v1` |Omitting it produces a "Not Found" SSE error. |=== diff --git a/modules/ROOT/pages/tinymceai-on-premises-troubleshooting.adoc b/modules/ROOT/pages/tinymceai-on-premises-troubleshooting.adoc index 40536b7376..bbc94494d9 100644 --- a/modules/ROOT/pages/tinymceai-on-premises-troubleshooting.adoc +++ b/modules/ROOT/pages/tinymceai-on-premises-troubleshooting.adoc @@ -252,7 +252,7 @@ Confirm `/health` is OK and a direct `curl` to `/v1/conversations` works before [cols="2,3",options="header"] |=== |Symptom |Fix -|Self-hosted model is slow through the AI service compared with raw `curl` |Co-locate the inference server with the AI service. Use a smaller or more quantized model. Disable telemetry during development (`LLM_TELEMETRY_ENABLED=false`). +|Self-hosted model is slow through the AI service compared with raw `curl` |Co-locate the inference server with the AI service. Use a smaller or more quantized model. Disable telemetry during development (`LLM_TELEMETRY_ENABLED=false`). This also stops AI Diagnostics recording. See xref:tinymceai-on-premises-production.adoc#ai-diagnostics[AI Diagnostics]. |Containers OOM or MySQL takes 60{plus} seconds to start (Colima) |Default Colima VM is too small. Run `colima stop && colima start --cpu 4 --memory 8 --disk 100`. |=== diff --git a/modules/ROOT/pages/tinymceai-on-premises.adoc b/modules/ROOT/pages/tinymceai-on-premises.adoc index 745d4fe0d1..f7c06575af 100644 --- a/modules/ROOT/pages/tinymceai-on-premises.adoc +++ b/modules/ROOT/pages/tinymceai-on-premises.adoc @@ -54,6 +54,9 @@ The shared secret (API Secret) exists only in the application back end (token en |Quick actions |Continue writing, improve writing, fix grammar, make shorter or longer, change tone, and translate. Chat actions, such as Summarize and Explain, run as conversations. +|Document Processing +|Apply one prompt to one or more HTML documents through the API. See xref:tinymceai-document-processing.adoc[Document Processing]. + |LLM provider flexibility |OpenAI, Anthropic, Google Gemini, Azure OpenAI, AWS Bedrock, Google Vertex AI, or any self-hosted OpenAI-compatible endpoint. Multiple providers can coexist. @@ -165,7 +168,7 @@ For a first-time deployment, progress through the guides in order. Each guide ca |HS256 signing model, required and optional claims, permissions reference, token endpoint examples for Express, Django, Flask, Laravel, Rails, .NET, Go, and Spring Boot, and multi-tenant deployment patterns. |xref:tinymceai-on-premises-frameworks.adoc[TinyMCE integration] -|Editor-side configuration: plugin options, token provider, authentication patterns, Cross-Origin Resource Sharing (CORS), and deployment checklists. +|Editor-side configuration: plugin options, token provider, authentication patterns, and Cross-Origin Resource Sharing (CORS). |xref:tinymceai-on-premises-production.adoc[Production deployment] |Kubernetes manifests, AWS ECS task definitions, horizontal scaling, security hardening, rate limiting, observability, backup and recovery, and upgrades. diff --git a/modules/ROOT/pages/tinymceai-permissions.adoc b/modules/ROOT/pages/tinymceai-permissions.adoc index 69083fe3cb..88a002d7eb 100644 --- a/modules/ROOT/pages/tinymceai-permissions.adoc +++ b/modules/ROOT/pages/tinymceai-permissions.adoc @@ -155,6 +155,8 @@ Uploading a file also requires `+ai:conversations:write+`. |Access to specific system actions. Examples: `ai:actions:system:improve-writing`, `ai:actions:system:fix-grammar`, `ai:actions:system:translate` |=== +For the full set of system action names, see the rows with a checkmark in the **API** column of the xref:tinymceai-actions.adoc#quick-actions-reference-table[Quick Actions reference table]. + Quick Actions that open in Chat, such as *Explain*, *Summarize*, and *Highlight key points*, and custom Quick Actions with `+type: 'chat'+`, send a conversation message. They require the xref:#conversation-permissions[conversation permissions] and the permission for the selected model. [[reviews-permissions]] @@ -177,6 +179,8 @@ Quick Actions that open in Chat, such as *Explain*, *Summarize*, and *Highlight |Access to specific system reviews. Examples: `ai:reviews:system:correctness`, `ai:reviews:system:clarity`, `ai:reviews:system:make-tone-professional` |=== +For the full set of system review names, see the **API review** column of xref:tinymceai-review.adoc#built-in-reviews[Built-in reviews]. + [[document-processing-permissions]] == Document Processing permissions @@ -311,6 +315,8 @@ Avoid `ai:models:*` in production to prevent unexpected access to new expensive When a user lacks required permissions, the API returns a `403 Forbidden` error with the code `+missing-permissions+`. The `+data.missingPermissions+` array lists the permissions that the token lacks. For the response body, see xref:tinymceai-api-overview.adoc#error-responses[Error responses]. Common issues include missing model permissions, file type restrictions, feature access without permission, and action/review access without permission. +A token whose `+auth.ai.permissions+` defines no permissions fails with the code `+no-permissions-defined+`. See xref:tinymceai-api-overview.adoc#error-codes[Error codes]. + [[related-features]] == Related features diff --git a/modules/ROOT/pages/tinymceai-review.adoc b/modules/ROOT/pages/tinymceai-review.adoc index 2c709a550c..f462b1273a 100644 --- a/modules/ROOT/pages/tinymceai-review.adoc +++ b/modules/ROOT/pages/tinymceai-review.adoc @@ -48,7 +48,7 @@ Review suggestions can be individually skipped or applied by clicking the corres - Completing the review with the currently applied suggestions (and skipping the rest) - Aborting the review and exiting (with all applied changes reverted) -While a review has pending suggestions, switching to the Chat sidebar or running a Quick Action opens a confirmation dialog. If the user confirms, the plugin discards the pending suggestions and returns the editor to normal editing. If the user cancels, the plugin keeps the pending suggestions. For the same behavior across several editors, see xref:tinymceai-multi-editor.adoc#discarding-suggestions[Discarding pending suggestions]. +While a review has pending suggestions, switching to the Chat sidebar or running a Quick Action opens a confirmation dialog. If the user confirms, the plugin discards the suggestions, resets the changes applied in the review, and returns the editor to normal editing. If the user cancels, the plugin keeps the pending suggestions. For the same behavior across several editors, see xref:tinymceai-multi-editor.adoc#discarding-suggestions[Discarding pending suggestions]. [[built-in-reviews]] == Built-in reviews @@ -82,7 +82,7 @@ a| |**Custom review** |— |xref:tinymceai-review.adoc#custom-review-choose-review[Custom review]: custom prompt and model; streams like other reviews. |✓ |✓ (custom review calls endpoint) -| |`+translate+` |Translate between languages with cultural adaptation. The request sets the target language in `+args.language+`. See https://tinymceai.api.tiny.cloud/v1/docs#tag/Reviews/operation/callSystemReview[Call a system review]. | |✓ +| |`+translate+` |Translate the content to another language. The request sets the target language in `+args.language+`. See https://tinymceai.api.tiny.cloud/v1/docs#tag/Reviews/operation/callSystemReview[Call a system review]. | |✓ |=== [NOTE] @@ -114,10 +114,12 @@ The Review plugin feature is built on top of the Reviews API, which provides RES Reviews use streaming output with Server-Sent Events for real-time feedback as suggestions are generated. Each review type is optimized for specific improvement tasks, providing consistent, high-quality analysis of text structure, style, and quality. Reviews provide specific, actionable recommendations for content improvement. +Each HTML element in the request content of a system or custom review needs a unique `+data-id+` attribute. Elements without a `+data-id+` are ignored. + [[reviews-system-reviews-api]] === System reviews -System reviews are built-in reviews for common use cases, and the request does not name a model. The API includes one endpoint for running system reviews, https://tinymceai.api.tiny.cloud/v1/docs#tag/Reviews/operation/callSystemReview[Call a system review], which takes the review name from the xref:tinymceai-review.adoc#built-in-reviews[API review] column in its path. Each HTML element in the request content needs a unique `+data-id+` attribute. +System reviews are built-in reviews for common use cases, and the request does not name a model. The API includes one endpoint for running system reviews, https://tinymceai.api.tiny.cloud/v1/docs#tag/Reviews/operation/callSystemReview[Call a system review], which takes the review name from the xref:tinymceai-review.adoc#built-in-reviews[API review] column in its path. Built-in system reviews including API names, descriptions, and whether each type is available in the Review sidebar or only through the API—are summarized in xref:tinymceai-review.adoc#built-in-reviews[Built-in reviews]. diff --git a/modules/ROOT/pages/tinymceai-streaming.adoc b/modules/ROOT/pages/tinymceai-streaming.adoc index b572eba2a2..0ff4d48935 100644 --- a/modules/ROOT/pages/tinymceai-streaming.adoc +++ b/modules/ROOT/pages/tinymceai-streaming.adoc @@ -27,6 +27,8 @@ Use the API reference for the operation being called—for example: The shared wire format and client-side parsing are covered in <> and <> on this page. +Conversations, actions, and Document Processing can stream a proposed modification as several `+modification-delta+` events. To join them, see xref:tinymceai-document-processing.adoc#fragments-in-a-stream[Fragments in a stream]. + [[sse-wire-format]] == SSE wire format @@ -40,6 +42,8 @@ event: data: .... +In version 1.1 reply streams, events also carry an SSE event ID on an `+id:+` line. To resume the stream, record the ID of the last event processed. See <>. + Parsing this format correctly (including chunk boundaries, multi-line `+data:+` fields, and comments) is easy to get wrong in hand-written loops. For production code, use a maintained SSE parser such as the https://www.npmjs.com/package/eventsource-parser[`eventsource-parser`] package. [[resumable-streams]] @@ -47,8 +51,8 @@ Parsing this format correctly (including chunk boundaries, multi-line `+data:+` Version 1.1 of the conversation message endpoints, under `+/v1.1+`, makes the reply stream more resilient. When replay is available for a reply, a client can: -* https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Messages-V1.1/operation/resumeStream[Resume an interrupted reply] with `+GET /v1.1/conversations/{conversationId}/messages/{messageId}/stream+`. Set `+lastEventId+` to the ID of the last SSE event the client processed, or to `+0-0+` to replay the whole reply. -* https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Messages-V1.1/operation/cancelStream[Cancel a reply in progress] with `+DELETE+` on the same path. The content already generated is kept, and the stored message status becomes `+cancelled+`. +* https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Messages-V1.1/operation/resumeStream[Resume an interrupted reply] with `+GET /v1.1/conversations/{conversationId}/messages/{messageId}/stream+`. The `+messageId+` comes from the `+message-metadata+` event of the reply stream. Set `+lastEventId+` to the ID of the last SSE event the client processed, or to `+0-0+` to replay the whole reply. +* https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Messages-V1.1/operation/cancelStream[Cancel a reply in progress] with `+DELETE+` on the same path. The stored message status becomes `+cancelled+`. Resuming a cancelled reply ends with a final `+error+` event that closes the stream. Some replies stream without replay support. The reply still streams, but the resume and cancel operations are not available for it. For the request that starts a version 1.1 reply, see https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Messages-V1.1/operation/createMessageV2[Send a message (V1.1)]. diff --git a/modules/ROOT/pages/tinymceai.adoc b/modules/ROOT/pages/tinymceai.adoc index a8b95aa39b..808f180541 100644 --- a/modules/ROOT/pages/tinymceai.adoc +++ b/modules/ROOT/pages/tinymceai.adoc @@ -29,13 +29,13 @@ The {pluginname} plugin can be deployed with either a {cloudname} or a self-host * *{cloudname}*: load the plugin from the {cloudname} CDN. * *Self-hosted*: from {productname} 8.7.0, install the plugin from the `+tinymce-premium+` NPM package, or as a standalone addon `.zip` download from the link:{accountpageurl}[{accountpage}]. -The `+tinymceai+` plugin is distributed only as a standalone addon. It is not included in any {productname} ZIP bundle. +The `+tinymceai+` plugin is distributed only as an addon. It is not included in any {productname} ZIP bundle. For self-hosted installation steps, see xref:npm-projects.adoc#install-premium-plugins[Install premium plugins from NPM] or xref:installation-zip.adoc[Installing {productname} using a .zip file]. [NOTE] ==== -The plugin requires an AI service to operate. Use the hosted {cloudname} AI service, or deploy the xref:tinymceai-on-premises.adoc[self-hosted AI service] to keep content within the host network. In both cases, a xref:tinymceai-jwt-authentication-intro.adoc[JWT token endpoint] handles authentication. +The plugin requires an AI service to operate. Use the hosted {cloudname} AI service, or deploy the xref:tinymceai-on-premises.adoc[self-hosted AI service] to store content within the host network. Data sent to the configured LLM provider is processed by that provider. In both cases, a xref:tinymceai-jwt-authentication-intro.adoc[JWT token endpoint] handles authentication. ==== [[basic-setup]] From 54db7fcc55a5e4843603aad155d58a7458170044 Mon Sep 17 00:00:00 2001 From: Karl Kemister-Sheppard Date: Mon, 9 Nov 2026 12:06:19 +1000 Subject: [PATCH 3/9] TINYDOC-3686: Scope the JWT signing algorithm and aud claim to Tiny Cloud-hosted and on-premises deployments. --- modules/ROOT/pages/tinymceai-jwt-authentication-intro.adoc | 6 ++++-- modules/ROOT/pages/tinymceai-on-premises-jwt.adoc | 2 +- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/modules/ROOT/pages/tinymceai-jwt-authentication-intro.adoc b/modules/ROOT/pages/tinymceai-jwt-authentication-intro.adoc index 177d576f08..178fb8a10c 100644 --- a/modules/ROOT/pages/tinymceai-jwt-authentication-intro.adoc +++ b/modules/ROOT/pages/tinymceai-jwt-authentication-intro.adoc @@ -10,7 +10,7 @@ [NOTE] ==== -This page covers JWT authentication for the *{cloudname}-hosted* AI service, where the `aud` claim is set to the Tiny Cloud API key and tokens are signed with RS256. For on-premises deployments, the `aud` claim is the Environment ID from the Management Panel and tokens are signed with HS256. See xref:tinymceai-on-premises-jwt.adoc[JWT authentication for the on-premises AI service]. +This page covers JWT authentication for the *{cloudname}-hosted* AI service, where the `aud` claim is set to the {cloudname} API key and tokens are signed with RS256. For on-premises deployments, the `aud` claim is the Environment ID from the Management Panel and tokens are signed with HS256. See xref:tinymceai-on-premises-jwt.adoc[JWT authentication for the on-premises AI service]. ==== {productname} recommends using the libraries listed on link:https://www.jwt.io/libraries[jwt.io/libraries] to create JWT tokens. These libraries support the algorithms required by {pluginname}. For details on supported algorithms, see xref:#supported-algorithms[Supported Algorithms]. @@ -219,7 +219,7 @@ The signature is created by encoding the header and payload using Base64URL, the [[supported-algorithms]] === Supported Algorithms -The {productname} AI service does not support symmetrical encryption algorithms, such as `HS256`. The xref:tinymceai-on-premises-jwt.adoc[on-premises service] uses `HS256`. {companyname} recommends using the `RS256` algorithm. The following algorithms are supported: +The {cloudname}-hosted AI service does not support symmetric signing algorithms, such as `HS256`. {companyname} recommends signing tokens with `RS256`. The following algorithms are supported: * RS256 * RS384 @@ -228,6 +228,8 @@ The {productname} AI service does not support symmetrical encryption algorithms, * PS384 * PS512 +On-premises deployments use different signing: tokens are signed with `HS256` using the API Secret, and the `aud` claim is the Environment ID. See xref:tinymceai-on-premises-jwt.adoc[JWT authentication for the on-premises AI service]. + For details on each of these algorithms, visit: link:https://tools.ietf.org/html/rfc7518#section-3[RFC 7518, JSON Web Algorithms (JWA) Section 3 - Cryptographic Algorithms for Digital Signatures and MACs]. [[token-requests]] diff --git a/modules/ROOT/pages/tinymceai-on-premises-jwt.adoc b/modules/ROOT/pages/tinymceai-on-premises-jwt.adoc index da1336b759..5c99ae8e60 100644 --- a/modules/ROOT/pages/tinymceai-on-premises-jwt.adoc +++ b/modules/ROOT/pages/tinymceai-on-premises-jwt.adoc @@ -9,7 +9,7 @@ This page covers *authentication between the application back end and the AI ser Before configuring JWT, complete the xref:tinymceai-on-premises-database.adoc[data layer] and xref:tinymceai-on-premises-providers.adoc[LLM provider] setup. After JWT, proceed to xref:tinymceai-on-premises-frameworks.adoc[TinyMCE integration] to wire the editor to the token endpoint. -The on-premises AI service uses *HS256* (HMAC-SHA256, symmetric shared secret) for JSON Web Token (JWT) authentication. This is different from the Tiny Cloud AI service, which uses RS256. +The on-premises AI service uses *HS256* (HMAC-SHA256, symmetric shared secret) for JSON Web Token (JWT) authentication, and the `aud` claim is the Environment ID. This is different from the {cloudname}-hosted AI service, where tokens are signed with RS256 and the `aud` claim is the {cloudname} API key. [WARNING] -- From c916559fca44cdd408bca56ca938e4cd39623764 Mon Sep 17 00:00:00 2001 From: Karl Kemister-Sheppard Date: Mon, 9 Nov 2026 12:24:57 +1000 Subject: [PATCH 4/9] TINYDOC-3686: Frame stored conversation operations around back-end tasks and link the API reference for the rest. --- modules/ROOT/pages/tinymceai-chat.adoc | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/modules/ROOT/pages/tinymceai-chat.adoc b/modules/ROOT/pages/tinymceai-chat.adoc index 2d89eb4698..0d2cc123a6 100644 --- a/modules/ROOT/pages/tinymceai-chat.adoc +++ b/modules/ROOT/pages/tinymceai-chat.adoc @@ -307,13 +307,13 @@ A message request can also pass `+extraHttpHeaders+` so the service can download [[conversations-api-stored]] === Working with stored conversations -The Chat history in the sidebar shows the conversations and messages that the AI service stores. The following operations read and manage the same data: +The AI service stores each conversation and its messages. The Chat history in the sidebar shows the same data. Back-end code can work with the stored conversations for tasks such as: -* https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversations/operation/getConversations[List conversations]. -* https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversations/operation/getConversation[Get a conversation], https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversations/operation/updateConversation[update a conversation] (for example, to rename or pin it), or https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversations/operation/deleteConversation[delete a conversation]. -* https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Messages/operation/getMessages[List the messages in a conversation]. -* https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Messages/operation/addConversationMessageRating[Rate a reply] or https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Messages/operation/updateMessage[update a message]. -* For back-end administration, a token with the `+ai:admin+` permission can https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Admin/operation/adminListConversations[list], https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Admin/operation/AdminGetConversation[get], and https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Admin/operation/adminDeleteConversation[delete] the conversations of any user. Never return an `+ai:admin+` token to the editor. See xref:tinymceai-permissions.adoc#admin-permissions[Admin permissions]. +* *Finding the conversations for one document.* When xref:tinymceai.adoc#content_id[`+content_id+`] is set, the plugin creates each conversation in a group with that value. Pass the same value as `+group+` to https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversations/operation/getConversations[list conversations] to get only the conversations for that document. +* *Collecting feedback on replies.* https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Messages/operation/addConversationMessageRating[Rate a reply] to record whether a user found it useful. +* *Managing conversations across users.* A token with the `+ai:admin+` permission can read and delete the conversations of any user through the https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Admin[Conversation Admin] operations. Never return an `+ai:admin+` token to the editor. See xref:tinymceai-permissions.adoc#admin-permissions[Admin permissions]. + +For every operation and its parameters, see https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversations[Conversations] and https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Messages[Conversation Messages] in the API reference. [[conversations-streaming]] === Streaming Responses From c151d0182f45566df652ae29707fb375c8d5b1a6 Mon Sep 17 00:00:00 2001 From: Karl Kemister-Sheppard Date: Mon, 9 Nov 2026 13:05:27 +1000 Subject: [PATCH 5/9] TINYDOC-3686: Align the extraHttpHeaders and reply rating descriptions with the API reference. --- modules/ROOT/pages/tinymceai-chat.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/tinymceai-chat.adoc b/modules/ROOT/pages/tinymceai-chat.adoc index 0d2cc123a6..675ffd7403 100644 --- a/modules/ROOT/pages/tinymceai-chat.adoc +++ b/modules/ROOT/pages/tinymceai-chat.adoc @@ -302,7 +302,7 @@ The `+capabilities+` object of a https://tinymceai.api.tiny.cloud/v1/docs#tag/Co Web search is separate from the https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Web-Resources[Conversation Web Resources] endpoints, which attach the content of one known URL to the conversation. -A message request can also pass `+extraHttpHeaders+` so the service can download images in the message content that require authentication. +When a document in the conversation references images stored behind authentication, pass `+extraHttpHeaders+` in the https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Messages/operation/createMessage[message request] so the AI can fetch and describe those images. The headers are keyed by domain, and the service sends them only to the domains listed. [[conversations-api-stored]] === Working with stored conversations @@ -310,7 +310,7 @@ A message request can also pass `+extraHttpHeaders+` so the service can download The AI service stores each conversation and its messages. The Chat history in the sidebar shows the same data. Back-end code can work with the stored conversations for tasks such as: * *Finding the conversations for one document.* When xref:tinymceai.adoc#content_id[`+content_id+`] is set, the plugin creates each conversation in a group with that value. Pass the same value as `+group+` to https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversations/operation/getConversations[list conversations] to get only the conversations for that document. -* *Collecting feedback on replies.* https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Messages/operation/addConversationMessageRating[Rate a reply] to record whether a user found it useful. +* *Recording which suggestions users accept.* https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Messages/operation/addConversationMessageRating[Rate a reply] to record how many of its suggested changes the user accepted. * *Managing conversations across users.* A token with the `+ai:admin+` permission can read and delete the conversations of any user through the https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Admin[Conversation Admin] operations. Never return an `+ai:admin+` token to the editor. See xref:tinymceai-permissions.adoc#admin-permissions[Admin permissions]. For every operation and its parameters, see https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversations[Conversations] and https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Messages[Conversation Messages] in the API reference. From a7c7e8bbb0ed71dda3b3568be79d3ae49fbe31dc Mon Sep 17 00:00:00 2001 From: Karl Kemister-Sheppard Date: Mon, 9 Nov 2026 13:11:29 +1000 Subject: [PATCH 6/9] TINYDOC-3686: Recommend setting content_id for Chat history and describe the behavior without it. --- modules/ROOT/pages/tinymceai-chat.adoc | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/pages/tinymceai-chat.adoc b/modules/ROOT/pages/tinymceai-chat.adoc index 675ffd7403..cf50179239 100644 --- a/modules/ROOT/pages/tinymceai-chat.adoc +++ b/modules/ROOT/pages/tinymceai-chat.adoc @@ -246,7 +246,9 @@ image::tinymceai/tinymce-ai-chat-diff-mode-reject-suggestion-overlay.png[{plugin [[chat-history]] == Chat history -All past conversations appear in the Chat history. To show only the conversations for one document, set xref:tinymceai.adoc#content_id[`+content_id+`]. Click the image:icons/restore-draft.svg[Chat history icon,24px] button in the chat header to open the list. Click a conversation to reopen it, or use the menu on each entry to pin, rename, or delete it. Click **AI Chat** to return from the history view to the active conversation. +Set xref:tinymceai.adoc#content_id[`+content_id+`] to a unique ID for each document, such as the ID of the document in the application. The plugin then stores each conversation with that ID, and the Chat history lists only the conversations for the open document, so a user who reopens the document finds its earlier conversations there. Without `+content_id+`, the Chat history lists all of the user's conversations, from every document. + +Click the image:icons/restore-draft.svg[Chat history icon,24px] button in the chat header to open the list. Click a conversation to reopen it, or use the menu on each entry to pin, rename, or delete it. Click **AI Chat** to return from the history view to the active conversation. The list shows pinned conversations under **Pinned**, and the other conversations under **History**. From 6f4466cc9c06b4d759c28a9ec7b0fad3023a40d2 Mon Sep 17 00:00:00 2001 From: Karl Kemister-Sheppard Date: Mon, 9 Nov 2026 14:15:17 +1000 Subject: [PATCH 7/9] TINYDOC-3686: List the API message flow as ordered steps with optional attachments. --- modules/ROOT/pages/tinymceai-chat.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/modules/ROOT/pages/tinymceai-chat.adoc b/modules/ROOT/pages/tinymceai-chat.adoc index cf50179239..b52e0a8ce4 100644 --- a/modules/ROOT/pages/tinymceai-chat.adoc +++ b/modules/ROOT/pages/tinymceai-chat.adoc @@ -291,11 +291,11 @@ The AI remembers everything that has been shared and builds on it throughout the [[conversations-api-flow]] === Sending a message through the API -Sending a message through the API takes three requests. The token needs the conversation permissions for each request. See xref:tinymceai-permissions.adoc#conversation-permissions[Conversation permissions]. +To send a message through the API, follow these steps. The token needs the conversation permissions for each request. See xref:tinymceai-permissions.adoc#conversation-permissions[Conversation permissions]. . https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversations/operation/createConversation[Create the conversation]. -. Attach content: an https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Documents/operation/createDocument[HTML document], a https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Files/operation/uploadFile[file], or a https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Web-Resources/operation/downloadWebResources[web page]. File size limits are listed in xref:tinymceai-limits.adoc#file-limits[File limits]. -. https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Messages/operation/createMessage[Send the message]. The message lists each attached item by its ID in the `+content+` array. See the example in xref:tinymceai-models.adoc#model-selection[Model Selection]. The service streams the reply with Server-Sent Events (SSE). See xref:tinymceai-chat.adoc#conversations-streaming[Streaming responses]. +. Optional: attach content to the conversation, with one request for each item. Attach an https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Documents/operation/createDocument[HTML document], a https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Files/operation/uploadFile[file], or a https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Web-Resources/operation/downloadWebResources[web page]. Each request returns the `+id+` of the attached item. File size limits are listed in xref:tinymceai-limits.adoc#file-limits[File limits]. +. https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Messages/operation/createMessage[Send the message], with each attached item in the `+content+` array as its type and `+id+`. See the example in xref:tinymceai-models.adoc#model-selection[Model Selection]. The service streams the reply with Server-Sent Events (SSE). See xref:tinymceai-chat.adoc#conversations-streaming[Streaming responses]. [[conversations-api-capabilities]] === API capabilities From 8f83bbc516f2440072419c59abf389e0b55cdf48 Mon Sep 17 00:00:00 2001 From: Karl Kemister-Sheppard Date: Mon, 9 Nov 2026 14:29:00 +1000 Subject: [PATCH 8/9] TINYDOC-3686: Clarify that the web search toggle makes search available and the model decides whether to search. --- modules/ROOT/pages/tinymceai-chat.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/tinymceai-chat.adoc b/modules/ROOT/pages/tinymceai-chat.adoc index b52e0a8ce4..9825673a96 100644 --- a/modules/ROOT/pages/tinymceai-chat.adoc +++ b/modules/ROOT/pages/tinymceai-chat.adoc @@ -96,7 +96,7 @@ tinymce.init({ Web search in Chat allows the AI to access and retrieve real-time information from the internet. Instead of relying only on pre-trained knowledge, the model can search the web to find up-to-date facts, verify details, and provide more accurate, current answers. -The model searches the web only when web search is enabled for the message. For models that support web search, turn on the **Web search** toggle image:icons-premium/web-search.svg[Web search icon,24px] below the prompt input. +To make web search available, turn on the **Web search** toggle image:icons-premium/web-search.svg[Web search icon,24px] below the prompt input. The toggle is available only when the selected model supports web search and the token includes the web search permission. See xref:tinymceai-permissions.adoc#conversation-permissions[Conversation permissions]. With the toggle on, the model decides from the prompt whether to search the web. A reply that used web search shows **Searched the internet for insights**. With the toggle off, the model does not search the web. [[reasoning]] === Reasoning From c0d663c089c7d010e3f9da5d14eb7037b262b308 Mon Sep 17 00:00:00 2001 From: Karl Kemister-Sheppard Date: Mon, 9 Nov 2026 14:38:49 +1000 Subject: [PATCH 9/9] TINYDOC-3686: Point to the Change tone toolbar menu button for tones on the toolbar. --- modules/ROOT/pages/tinymceai-actions.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/tinymceai-actions.adoc b/modules/ROOT/pages/tinymceai-actions.adoc index 149813856e..0eadce80fa 100644 --- a/modules/ROOT/pages/tinymceai-actions.adoc +++ b/modules/ROOT/pages/tinymceai-actions.adoc @@ -119,7 +119,7 @@ Custom actions can be added to the list, and default actions can be removed or r The following table lists built-in Quick Actions. * The **Editor** column is the label in the Quick Actions menu when that action is available in the editor. -* The **Menu or control ID** column lists values for `tinymceai_quickactions_menu`, `tinymceai_quickactions_chat_prompts`, `tinymceai_quickactions_change_tone_menu`, and the toolbar when adding individual controls (see xref:tinymceai-actions.adoc#configuring-quick-actions-menu[Configuring Quick Actions menu]). The `ai-quickactions-tone-*` identifiers are menu items only and cannot be added to the toolbar. +* The **Menu or control ID** column lists values for `tinymceai_quickactions_menu`, `tinymceai_quickactions_chat_prompts`, `tinymceai_quickactions_change_tone_menu`, and the toolbar when adding individual controls (see xref:tinymceai-actions.adoc#configuring-quick-actions-menu[Configuring Quick Actions menu]). To put tones on the toolbar, add the `ai-quickactions-change-tone` menu button. It opens the tones set in xref:tinymceai.adoc#tinymceai_quickactions_change_tone_menu[`+tinymceai_quickactions_change_tone_menu+`]. The individual `ai-quickactions-tone-*` identifiers are menu items only, so they cannot be added to the toolbar. * The **System `actionName` or quick-action prompt id** column is the service identifier. Preview actions use a system `actionName` with the xref:tinymceai-actions.adoc#actions-api[Actions API]. Chat actions use a quick-action prompt id and xref:tinymceai-chat.adoc[Chat] with a pre-filled prompt, not the system actions API. [cols="1,3,2,3,1,1",options="header"]