tavus-cli 0.9.2__tar.gz → 0.10.0__tar.gz

tavus_cli-0.10.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.10.0"
+}

{tavus_cli-0.9.2 → tavus_cli-0.10.0}/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.10.0](https://github.com/Tavus-Engineering/tavus-mcp/compare/v0.9.3...v0.10.0) (2026-10-14)
+
+
+### Features
+
+* route agents to build_and_verify and let it change existing PALs ([#72](https://github.com/Tavus-Engineering/tavus-mcp/issues/72)) ([0a993f9](https://github.com/Tavus-Engineering/tavus-mcp/commit/0a993f96219dde3cc6c27405d6741adb8fc69523))
+
+## [0.9.3](https://github.com/Tavus-Engineering/tavus-mcp/compare/v0.9.2...v0.9.3) (2026-10-13)
+
+
+### Bug Fixes
+
+* **worker:** accept any loopback port and legacy MCP client IDs at sign-in ([#70](https://github.com/Tavus-Engineering/tavus-mcp/issues/70)) ([231a42c](https://github.com/Tavus-Engineering/tavus-mcp/commit/231a42c39806646c21ae07af3330927dbba5ea4a))
+
 ## [0.9.2](https://github.com/Tavus-Engineering/tavus-mcp/compare/v0.9.1...v0.9.2) (2026-10-10)
 
 

{tavus_cli-0.9.2 → tavus_cli-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tavus-cli
-Version: 0.9.2
+Version: 0.10.0
 Summary: Tavus CLI and MCP server for agentic PAL creation and editing.
 Requires-Python: >=3.11
 Requires-Dist: fastmcp>=2.0.0

{tavus_cli-0.9.2 → tavus_cli-0.10.0}/PROMPT.md

@@ -37,7 +37,7 @@ How to do the common things properly
 These are the contracts the server keeps. Exact parameters and response shapes are in the reference below; the order of operations is here, because that is what tends to get invented.
 
 - Building a new PAL. Use `tavus_pal_build_and_verify`; it is the standard path. You run the interview first: ask me plain questions, up to 12, about who the PAL talks to, what a good conversation achieves, the tone, what it must never say or do, what it should know (links to documents), and what it should do in my app. Ask only what my description leaves open. Pass my description as `prompt`, the questions and my answers as `interview`, and your summary of each part as `briefs`. The call takes one to three minutes. It drafts the personality, objectives, guardrails and greeting, picks a face unless I asked for one (`face_id`), publishes the PAL, runs test conversations and judges them. Read `verdict.overall` (`pass`, `partial` or `fail`), then the summary and any failing evidence, before you tell me it works. Tools can only be attached once the PAL exists, so the build's test turns run without them and tool checks in the verdict fail; attach the tools, then rerun those turns with chat mode before you tell me the tools work. Give me the `pal_url` it returns; that opens the PAL in the PAL Maker. Use `tavus_pal_create` or `tavus_quickstart` only when I hand you a finished system prompt and ask you to skip the build.
-- Changing an existing PAL. Call `tavus_pal_get` and `tavus_describe_pal_options` first, and take ids and patch paths from what they return. Make the smallest change with `tavus_patch_pal` (JSON Patch operations such as `replace` on `/greeting`), or use the dedicated tools for capabilities, Knowledge and tools. A change applies to every conversation the PAL starts from then on, including on my live site, so tell me what will change and get a yes before patching a PAL that is already in use.
+- Changing an existing PAL. For a change to what the PAL does or shows, such as a new step, an on-screen scorecard or quiz, web search, or memory, call `tavus_pal_build_and_verify` with its `pal_id`, my request as `prompt`, and only the `briefs` for the parts that should change. Put built-in capabilities in `briefs.skills`. The same PAL Maker drafters edit the PAL and leave the rest alone, then it publishes and tests the PAL. Read `drafted` and `builtin_changes` in the result to see what changed. For an exact edit, such as a new greeting, call `tavus_pal_get` and `tavus_describe_pal_options` first, and take ids and patch paths from what they return. Make the smallest change with `tavus_patch_pal` (JSON Patch operations such as `replace` on `/greeting`), or use the dedicated tools for capabilities, Knowledge and tools. A change applies to every conversation the PAL starts from then on, including on my live site, so tell me what will change and get a yes before changing a PAL that is already in use.
 - Giving the PAL a tool. Check `tavus_tool_list` first and attach an existing tool when its name, parameters and delivery fit. When you create a new one that overlaps an existing tool, tell me which tool you saw and why it does not fit. The tool's `description` is what tells the PAL when to call it, so write it as an instruction. `delivery` decides where the call goes: `{ "app_message": true }` (the default) sends it to the page running the conversation, and `delivery.api` makes Tavus call a backend URL. Then write the handler in this repo with the exact tool name and parameter schema, so the two halves match. On a page that uses `<tavus-embed>` or `<tavus-widget>`, the call arrives as `tavus:tool-call` `{ name, arguments, tool_call_id }` with `arguments` as a JSON string, and the page replies with `sendMessage({ event_type: "conversation.tool_result", properties: { tool_call_id, output, status: "success" } })`; the host communication page below has the full contract. A tool that is not attached to the PAL never fires, however the code is wired.
 - Giving the PAL knowledge. Create a Knowledge document from a URL anyone can reach with `tavus_document_create`, then attach it with `tavus_pal_knowledge_add`. The hosted server cannot read files on my machine; for a local file, ask me to upload it in the PAL Maker's Knowledge section or to host it at a URL. Before you tell me what a document says, read what Tavus indexed with `tavus_document_chunks`.
 - Testing by text. `tavus_chat_start` starts a text-only conversation with the PAL, `tavus_chat_turn` sends one message and waits for the reply, and `tavus_chat_end` ends it. Always end the conversations you start. The first turn is slower while the conversation starts up. Replies are not deterministic, so judge behaviour (did it ask for the order number, did it refuse the pricing promise) rather than exact wording.

{tavus_cli-0.9.2 → tavus_cli-0.10.0}/docs/builder-guidance.md

@@ -17,12 +17,32 @@ Portal-only tool names, UI instructions, or capabilities this server cannot
 configure. In particular, the hosted attach tool takes `capability`, while the
 local tool takes `capability_id`.
 
+## Instruction order and length
+
+Some clients keep only the first 4,096 characters of the server instructions.
+Claude Code is one of them, and it also defers MCP tools, so an agent often
+picks a tool from the instructions and tool names alone. Keep the routing rules
+first and the whole set under 4,096 characters; the Worker guidance test fails
+when either rule breaks.
+
+- `instructions[0]` routes new builds to `tavus_pal_build_and_verify`. Both
+  servers send it first.
+- `hosted_instructions` routes changes to existing PALs through
+  `tavus_pal_build_and_verify` with `pal_id`. Only the hosted Worker has that
+  parameter, so it inserts these right after `instructions[0]`.
+- The remaining `instructions` are the capability rules.
+
 ## Behavior checks
 
-Use these prompts to evaluate capability selection with an MCP client:
+Use these prompts to evaluate tool selection with an MCP client:
 
 | Request | Expected behavior |
 | --- | --- |
+| Build a PAL that shows trainees a scorecard after each roleplay. | Call `tavus_pal_build_and_verify`, with the scorecard in `briefs.skills` on the hosted connector. Do not call `tavus_pal_create`. |
+| Here is the system prompt I drafted; set it up so trainees see a scorecard. | Same as above. A drafted prompt is a brief, not a request to skip the build. |
+| Add an on-screen scorecard to my PAL p123. | Hosted: `tavus_pal_build_and_verify` with `pal_id` and `briefs.skills`. Local: attach Magic Canvas. |
+| Change the greeting of my PAL p123 to "Hi". | `tavus_patch_pal` on `/greeting`. |
+| Create this PAL from my finished prompt and skip the build. | `tavus_pal_create`. |
 | Show a training scorecard after each exercise. | Attach Magic Canvas with `text` and/or `chart` and usage guidance in the same call. Do not create `record_training_scorecard`. |
 | Collect an email address on screen. We have no backend yet. | Attach Magic Canvas with `input`. Explain that delivery can be connected later. Do not invent an endpoint. |
 | Show the score and save it to our existing API. | Configure Magic Canvas for display and separately reuse or create a tool for the verified API. |
@@ -33,9 +53,9 @@ Use these prompts to evaluate capability selection with an MCP client:
 | Remember returning visitors. | Attach Memory and add a first-visit fallback in the prompt and greeting. |
 | Do not show anything on screen. | Respect the decline; do not attach Magic Canvas. |
 
-The automated tests verify that clients receive the shared guidance and that
-the scorecard configuration travels through the MCP tools to the skills API and
-back, using a mocked API. They do not evaluate a model's tool choice or prove
-live rendering. For a live evaluation, record the model's tool calls, read back
+The automated tests verify that clients receive the guidance in the right order
+and length, and that the scorecard configuration travels through the MCP tools
+to the skills API and back, using a mocked API. They do not evaluate a model's
+tool choice or prove live rendering. For a live evaluation, record the model's tool calls, read back
 the saved capability, and inspect the canvas during a call before claiming the
 scorecard displayed.

{tavus_cli-0.9.2 → tavus_cli-0.10.0}/packages/tavus/pyproject.toml

@@ -1,11 +1,11 @@
 [project]
 name = "tavus"
-version = "0.9.2" # x-release-please-version
+version = "0.10.0" # x-release-please-version
 description = "Official alias for tavus-cli, the Tavus CLI and MCP server."
 readme = "README.md"
 requires-python = ">=3.11"
 dependencies = [
-  "tavus-cli==0.9.2", # x-release-please-version
+  "tavus-cli==0.10.0", # x-release-please-version
 ]
 
 [project.urls]

{tavus_cli-0.9.2 → tavus_cli-0.10.0}/packages/tavus-mcp/pyproject.toml

@@ -1,11 +1,11 @@
 [project]
 name = "tavus-mcp"
-version = "0.9.2" # x-release-please-version
+version = "0.10.0" # x-release-please-version
 description = "Official alias for tavus-cli, which provides the tavus-mcp MCP server."
 readme = "README.md"
 requires-python = ">=3.11"
 dependencies = [
-  "tavus-cli==0.9.2", # x-release-please-version
+  "tavus-cli==0.10.0", # x-release-please-version
 ]
 
 [project.urls]

{tavus_cli-0.9.2 → tavus_cli-0.10.0}/plugins/tavus-pal/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "tavus-pal",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Create, edit, and test Tavus PALs: digital humans with a face, voice, knowledge, and conversational behavior. Uses the Tavus hosted MCP server and your connected Tavus account.",
   "author": {
     "name": "Tavus",
@@ -37,6 +37,7 @@
         "logoDark": "./assets/icon-dark.svg"
       },
       "review": {
+        "demo_recording_url": "https://tavus-mcp-review.pages.dev/tavus-openai-review-demo-2026-09-10-19f4128cd7a5cbc4.mp4",
         "commerce": false,
         "commerce_description": "Users access their existing Tavus account entitlements. This plugin does not sell PALs, subscriptions, or credits, collect payment details, or initiate checkout.",
         "test_cases": {

{tavus_cli-0.9.2 → tavus_cli-0.10.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tavus-cli"
-version = "0.9.2"
+version = "0.10.0"
 description = "Tavus CLI and MCP server for agentic PAL creation and editing."
 readme = "README.md"
 requires-python = ">=3.11"

{tavus_cli-0.9.2 → tavus_cli-0.10.0}/skills/tavus-agentic-pals/SKILL.md

@@ -220,10 +220,12 @@ Autonomous build + verify:
   persona, joins its Daily room, executes its tool calls, publishes, selects a
   face, smoke-tests the PAL over Daily, and returns a judge verdict.
 - Hosted connector: `tavus_pal_build_and_verify(prompt, interview?, briefs?,
-  face_id?, pal_name?, probes?)` requires the calling agent to interview the
-  creator first. It records that transcript, runs the portal's artifact
-  drafters, publishes, selects a face, smoke-tests through the Tavus HTTP
-  bridge, and returns a judge verdict.
+  face_id?, pal_name?, probes?, pal_id?)` requires the calling agent to
+  interview the creator first. It records that transcript, runs the portal's
+  artifact drafters, publishes, selects a face, smoke-tests through the Tavus
+  HTTP bridge, and returns a judge verdict. With `pal_id`, it changes that PAL
+  instead: only the briefed drafters run, and the PAL keeps its face. Put
+  built-in capabilities such as an on-screen scorecard in `briefs.skills`.
 
 Pass `probes` on either surface to pin exact validation prompts; otherwise Tavus
 generates them from the PAL spec. Neither path needs a browser or a client-side

{tavus_cli-0.9.2 → tavus_cli-0.10.0}/skills/tavus-agentic-pals/references/build-and-verify.md

@@ -43,9 +43,28 @@ tavus_pal_build_and_verify(
   face_id?,        # optional override; RQH selects one when omitted
   pal_name?,       # optional explicit name
   probes?,         # optional exact validation prompts; generated when omitted
+  pal_id?,         # optional existing PAL to change instead of building one
 )
 ```
 
+### Changing an existing PAL (hosted connector)
+
+Pass `pal_id` to run the same drafters on an existing PAL. Put the requested
+change in `prompt` and fill only the `briefs` for the parts that should
+change; at least one brief is required. The other parts of the PAL are left
+as they are, and the PAL keeps its face unless `face_id` is given.
+
+Use `briefs.skills` for built-in capabilities: on-screen scorecards, quizzes,
+forms, and charts (Magic Canvas), web search, memory, and slide decks. The
+skills drafter attaches and configures them. Use `briefs.tools` only for an
+external action such as a webhook or API call.
+
+When the PAL has been used outside PAL Maker (a deployment, a conferencing
+identity, or a real conversation), RQH opens the session on the PAL's private
+PAL Maker draft. The edit lands there and publish copies it onto the live PAL.
+Publishing also publishes any unpublished PAL Maker edits on that PAL, so get
+the creator's agreement before changing a PAL they are editing in PAL Maker.
+
 The lower-level Python recipe retains `model` for backwards compatibility but
 ignores it. The authenticated RQH boundary always selects
 `tavus-pal-maker-gemma-4`; GPT-OSS, the old Gemma thinking model, and inline
@@ -66,6 +85,9 @@ tool payloads cannot override it.
     summary,
   },
   validated,
+  drafted?,             # hosted path: drafters that returned a change
+  builtin_changes?,     # hosted path: built-ins attached or detached on the
+                        # tools drafter's recommendation
   build_transcript?,    # local path
   refine_rounds_used?,  # local path
 }
@@ -75,8 +97,14 @@ tool payloads cannot override it.
 
 - A missing or inaccessible builder persona fails the local path; MCP never
   falls back to a synthetic prompt.
-- The hosted path always drafts the four core artifacts, even when the calling
-  agent supplies only a sparse set of briefs.
+- A new PAL on the hosted path always drafts the four core artifacts, even
+  when the calling agent supplies only a sparse set of briefs. A `pal_id`
+  change runs only the briefed drafters.
+- The tools drafter only recommends built-in capabilities. The hosted path
+  attaches a recommended Magic Canvas, Web Search, or Memory with default
+  settings when the skills drafter has not already attached it. It does not
+  attach Slide Presenter, which needs a deck's document ids; that case is
+  reported in `builtin_changes`.
 - Each path ends the CVI conversations it starts, including failed smoke tests.
 - Deployment tools are not run by the build-only recipe.
 

{tavus_cli-0.9.2 → tavus_cli-0.10.0}/src/tavus_mcp/__init__.py

@@ -1,4 +1,4 @@
 """Tavus CLI and MCP server package."""
 
 __all__ = ["__version__"]
-__version__ = "0.9.2"  # x-release-please-version
+__version__ = "0.10.0"  # x-release-please-version

tavus_cli-0.10.0/src/tavus_mcp/builder_guidance.json

@@ -0,0 +1,25 @@
+{
+  "instructions": [
+    "Build a new PAL with tavus_pal_build_and_verify. It runs the PAL Maker pipeline that Charlie uses, then publishes and tests the PAL. Use tavus_pal_create or tavus_quickstart only when the creator hands over a finished system prompt and asks to skip the build.",
+    "For an existing PAL, read tavus_pal_capabilities_list first and preserve unrelated settings and attachments. Configure built-ins with tavus_pal_capability_attach, tavus_pal_capability_patch, and tavus_pal_capability_detach.",
+    "Magic Canvas (magic_canvas) shows scorecards, running scores, charts, quizzes, forms, contact capture, text, and links during a call. A request to show a training scorecard means enabling Magic Canvas, not creating a tool such as record_training_scorecard. The PAL's own model drives the canvas; a saved tool or API response cannot draw on it. Model-generated quiz questions, scores, dice rolls, and random picks need no custom tool. Saving results to a backend is a separate step; recording data does not display it.",
+    "When the creator asks for on-screen interaction, attach magic_canvas with the needed magic_canvas_components and magic_canvas_usage_guidance in the same call: text and/or chart for a scorecard, input for forms, question for quizzes. Put one or two lines of when-to-show choreography in magic_canvas_usage_guidance, not in the system prompt. On attach, omitted components are disabled. If the use case only suggests a canvas, offer it once; a decline stays declined. Without a backend, say collection works on screen and delivery can be connected later; do not create a placeholder delivery tool.",
+    "Magic Canvas calendar collects date and time preferences and books nothing. Scheduling needs the creator's real HTTPS calendly.com booking link in scheduling_url, not a placeholder or scheduling_embed. Image and map output are not available.",
+    "Use slide_presenter to present an uploaded deck: display-ready document_ids, with slides_trigger=walk_the_deck for automatic narration or on_demand when the PAL should wait. For a presentation or sales use case, offer a deck once; Magic Canvas does not replace Slide Presenter.",
+    "Use web_search for current information the PAL needs during calls, such as weather, news, prices, and scores, and add when to look things up to the PAL's instructions; for weather, ask for the location first. Do not create get_weather or invent an endpoint. Research for building the PAL does not need Web Search attached.",
+    "Use perception for camera and screen awareness, not an invented view_screen tool. Use memory for returning participants, with a prompt and greeting that fall back gracefully for first-time visitors. Do not invent a custom tool for a missing integration or unsupported capability.",
+    "Create a saved tool only for a real external action, data lookup, or application event that built-ins do not cover. Check tavus_tool_list or tavus_describe_pal_options first and reuse a matching tool; if a new tool overlaps one, say why the existing one does not fit. Use an endpoint the creator supplied or that exists in their code, or an app-message handler their application implements. Never invent URLs or claim an unimplemented handler works. Attach tools with tavus_pal_tools_attach; inline layers.*.tools writes through tavus_patch_pal are rejected.",
+    "Knowledge uses document_ids, document_tags, and layers.knowledge_base. Use tavus_document_* for the library and tavus_pal_knowledge_* to attach. Reading a document does not attach it.",
+    "After a capability write, read tavus_pal_capabilities_list to confirm the saved config, and report only what the tools confirm. A build or text-test verdict does not prove a canvas displayed; do not claim that without a live visual check."
+  ],
+  "hosted_instructions": [
+    "To change what an existing PAL does or shows, including adding a built-in such as an on-screen scorecard, call tavus_pal_build_and_verify with its pal_id and only the briefs that should change. Put built-ins in briefs.skills and external actions in briefs.tools. Use tavus_patch_pal or the capability tools only for an exact setting the creator names."
+  ],
+  "tool_descriptions": {
+    "tavus_tool_create": "Create a saved tool for a real external action or application handler. Check built-in capabilities first: scorecards, quizzes, forms, charts, and on-screen text use tavus_pal_capability_attach with magic_canvas. A saved tool cannot render Magic Canvas. Backend recording is separate from on-screen display. Use web_search for weather or current information. Never invent an endpoint or placeholder handler.",
+    "tavus_pal_capability_attach": "Enable a built-in capability by intent. Use magic_canvas for scorecards, quizzes, forms, charts, and on-screen text; pass magic_canvas_components and magic_canvas_usage_guidance in this call. Use slide_presenter for decks, web_search for current information, perception for screen/camera awareness, and memory for returning participants. Read tavus_pal_capabilities_list afterward to verify the saved config.",
+    "tavus_pal_capability_patch": "Update an enabled built-in capability. For Magic Canvas, keep display choreography in magic_canvas_usage_guidance. The patch merges top-level config fields but replaces config.components when supplied. Read the saved config and preserve unchanged component settings, including any booking link, when changing components. Read tavus_pal_capabilities_list afterward to verify the saved config."
+  },
+  "magic_canvas_description": "Show scorecards, running scores, quizzes, forms, charts, text, and links during a call. The PAL's model drives the canvas; saved tools and API responses cannot render it. Use text or chart for a training scorecard, question for quizzes, and input for contact capture. Calendar collects preferences but books nothing. Scheduling needs a real HTTPS Calendly booking link. Image and map output are not available.",
+  "magic_canvas_usage_guidance": "One or two lines describing when to show each element, with one fixed variant per step. Keep this display choreography here rather than in the PAL's system prompt."
+}

{tavus_cli-0.9.2 → tavus_cli-0.10.0}/uv.lock

@@ -1303,7 +1303,7 @@ wheels = [
 
 [[package]]
 name = "tavus-cli"
-version = "0.9.2"
+version = "0.10.0"
 source = { editable = "." }
 dependencies = [
     { name = "fastmcp" },

{tavus_cli-0.9.2 → tavus_cli-0.10.0}/workers/tavus-mcp/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@tavus/tavus-mcp-worker",
-  "version": "0.9.2",
+  "version": "0.10.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@tavus/tavus-mcp-worker",
-      "version": "0.9.2",
+      "version": "0.10.0",
       "dependencies": {
         "@modelcontextprotocol/sdk": "^1.29.0",
         "agents": "^0.12.2",

{tavus_cli-0.9.2 → tavus_cli-0.10.0}/workers/tavus-mcp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tavus/tavus-mcp-worker",
-  "version": "0.9.2",
+  "version": "0.10.0",
   "private": true,
   "type": "module",
   "scripts": {

{tavus_cli-0.9.2 → tavus_cli-0.10.0}/workers/tavus-mcp/src/oauth.ts

@@ -18,6 +18,13 @@ const REGISTER_ROUTE = "/register";
 const CALLBACK_ROUTE = "/oauth/callback";
 const AUTHORIZATION_REQUEST_ROUTE = "/oauth/authorization-request";
 const DYNAMIC_CLIENT_PREFIX = "tavus-mcp-dcr";
+// Client IDs that /register issued before 2026-08-06 (#21). The Worker never
+// stored them, and /authorize accepted any client ID whose redirect was a
+// loopback URL. Clients such as Claude Code keep replaying the ID they cached
+// instead of registering again (anthropics/claude-code#84614), and the
+// rejection they get is a browser page they never see. Keeping the old rule
+// for these IDs, loopback only, lets them sign in without any stored state.
+const LEGACY_DYNAMIC_CLIENT_ID = /^tavus-mcp-[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/;
 const AUTHORIZATION_STATE_TTL_SECONDS = 10 * 60;
 const AUTHORIZATION_CODE_TTL_SECONDS = 5 * 60;
 
@@ -191,10 +198,37 @@ function findRegisteredRedirect(
   redirectUri: string,
 ): RegisteredOAuthClient | undefined {
   return clients.find(
-    (c) => c.client_id === clientId && c.redirect_uris.includes(redirectUri),
+    (c) =>
+      c.client_id === clientId &&
+      c.redirect_uris.some((registered) => redirectUriMatches(registered, redirectUri)),
   );
 }
 
+// RFC 8252 section 7.3: a native client takes an ephemeral port when it starts
+// the flow, so the authorization server MUST accept any port on a loopback
+// redirect URI. Everything else about the URI still has to match. HTTPS
+// callbacks need an exact match.
+function redirectUriMatches(registered: string, requested: string): boolean {
+  if (registered === requested) {
+    return true;
+  }
+  if (!isLoopbackUrl(registered) || !isLoopbackUrl(requested)) {
+    return false;
+  }
+  const a = new URL(registered);
+  const b = new URL(requested);
+  return (
+    a.protocol === b.protocol &&
+    a.hostname === b.hostname &&
+    a.pathname === b.pathname &&
+    a.search === b.search
+  );
+}
+
+function isLegacyDynamicClient(clientId: string): boolean {
+  return LEGACY_DYNAMIC_CLIENT_ID.test(clientId);
+}
+
 async function resolveRegisteredRedirect(
   env: Env,
   clientId: string,
@@ -208,7 +242,7 @@ async function resolveRegisteredRedirect(
   const signingSecret = oauthSigningSecret(env);
   if (signingSecret) {
     const dynamic = await verifyClientPayload(clientId, signingSecret);
-    if (dynamic?.redirect_uris.includes(redirectUri)) {
+    if (dynamic?.redirect_uris.some((registered) => redirectUriMatches(registered, redirectUri))) {
       return {
         client_id: clientId,
         redirect_uris: dynamic.redirect_uris,
@@ -217,6 +251,10 @@ async function resolveRegisteredRedirect(
     }
   }
 
+  if (isLegacyDynamicClient(clientId) && isLoopbackUrl(redirectUri)) {
+    return { client_id: clientId, redirect_uris: [redirectUri], name: "Tavus MCP Client" };
+  }
+
   return undefined;
 }
 
@@ -378,9 +416,10 @@ async function handleAuthorize(request: Request, env: Env, mcpRoute: string): Pr
 
   const registeredRedirect = await resolveRegisteredRedirect(env, clientId, redirectUri);
   if (!registeredRedirect) {
+    // This page is all the person sees; the MCP client never learns about it.
     return oauthError(
       "invalid_request",
-      "redirect_uri is not registered for this client.",
+      "redirect_uri is not registered for this client. Remove and re-add the Tavus MCP server in your client so it registers again.",
       400,
     );
   }
@@ -654,6 +693,10 @@ async function authenticateClient(request: Request, params: URLSearchParams, env
     }
     return secret ? null : clientId;
   }
+  // Legacy IDs were always public clients; see LEGACY_DYNAMIC_CLIENT_ID.
+  if (isLegacyDynamicClient(clientId)) {
+    return !secret && !basic ? clientId : null;
+  }
   const signingSecret = oauthSigningSecret(env);
   const dynamic = signingSecret ? await verifyClientPayload(clientId, signingSecret) : null;
   if (!dynamic || !signingSecret) return null;

{tavus_cli-0.9.2 → tavus_cli-0.10.0}/workers/tavus-mcp/src/tavus.ts

@@ -347,6 +347,13 @@ const CAPABILITY_ALIASES: Record<string, CapabilityId> = {
   "skill:memory": "memory",
 };
 
+// Some clients keep only the first 4,096 characters of server instructions,
+// so the routing rules lead and the whole set must stay under that limit.
+export function hostedInstructions(): string {
+  const [buildRouting, ...capabilityRules] = builderGuidance.instructions;
+  return [buildRouting, ...builderGuidance.hosted_instructions, ...capabilityRules].join("\n\n");
+}
+
 const KNOWLEDGE_BASE_SETTING_KEYS = new Set([
   "rag_score_threshold",
   "rag_n_chunks",
@@ -534,7 +541,7 @@ export function createTavusMcpServer(
         theme: "dark",
       },
     ],
-  }, { instructions: builderGuidance.instructions.join("\n\n") });
+  }, { instructions: hostedInstructions() });
   addToolIntent(server, authChallenge);
 
   server.tool(
@@ -608,7 +615,7 @@ export function createTavusMcpServer(
 
   server.tool(
     "tavus_pal_create",
-    "Create a PAL directly from supplied configuration and return its PAL Maker editor URL. This low-level operation does not draft or verify the PAL through the guided PAL Maker pipeline. Full-pipeline PALs default to tavus-gemma-4 unless layers.llm.model is supplied. Tools are first-class records referenced by top-level tool_ids; inline layers.llm.tools configuration is unsupported.",
+    "Create a PAL directly from supplied configuration and return its PAL Maker editor URL. This low-level operation does not draft or verify the PAL through the guided PAL Maker pipeline; for a new PAL, use tavus_pal_build_and_verify unless the creator hands over a finished system prompt and asks to skip the build. Full-pipeline PALs default to tavus-gemma-4 unless layers.llm.model is supplied. Tools are first-class records referenced by top-level tool_ids; inline layers.llm.tools configuration is unsupported.",
     {
       system_prompt: z.string().min(1).optional(),
       pal_name: z.string().default("Agentic Tavus PAL"),
@@ -666,7 +673,7 @@ export function createTavusMcpServer(
 
   server.tool(
     "tavus_patch_pal",
-    "Patch a PAL with validated JSON Patch operations. Attach first-class tools through top-level tool_ids or tavus_pal_tools_attach; legacy layers.llm.tools writes are rejected.",
+    "Patch a PAL with validated JSON Patch operations for an exact field edit. To change what a PAL does or shows, such as adding an on-screen scorecard, use tavus_pal_build_and_verify with pal_id instead. Attach first-class tools through top-level tool_ids or tavus_pal_tools_attach; legacy layers.llm.tools writes are rejected.",
     {
       pal_id: z.string().min(1),
       ops: z.array(JsonPatchOperationSchema).min(1),
@@ -1062,7 +1069,8 @@ export function createTavusMcpServer(
 
   server.tool(
     "tavus_tool_create",
-    builderGuidance.tool_descriptions.tavus_tool_create + " Attach the returned tool_id to a PAL with tavus_pal_tools_attach or top-level tool_ids.",
+    builderGuidance.tool_descriptions.tavus_tool_create +
+      " Attach the returned tool_id to a PAL with tavus_pal_tools_attach or top-level tool_ids. When the tool is part of building or changing a PAL, tavus_pal_build_and_verify (with pal_id for an existing PAL) drafts saved tools and built-ins together through briefs.tools and briefs.skills.",
     toolWriteFields,
     writeAnnotations("Create tool"),
     async (body) => toolResult(await client.create("tools", clean(body))),
@@ -1302,7 +1310,8 @@ export function createTavusMcpServer(
 
   server.tool(
     "tavus_pal_capability_attach",
-    builderGuidance.tool_descriptions.tavus_pal_capability_attach,
+    builderGuidance.tool_descriptions.tavus_pal_capability_attach +
+      " When the creator describes a change to an existing PAL rather than an exact setting, use tavus_pal_build_and_verify with pal_id and briefs.skills instead.",
     capabilityWriteSchema,
     {
       title: "Attach PAL capability",
@@ -1759,7 +1768,7 @@ export function createTavusMcpServer(
 
   server.tool(
     "tavus_quickstart",
-    "Create a PAL from a complete system prompt, select a stock face when none is supplied, and start a conversation. Returns the PAL, conversation, and selected face. This quick setup does not gather an interview or run the guided PAL Maker build and verification pipeline.",
+    "Create a PAL from a complete system prompt, select a stock face when none is supplied, and start a conversation. Returns the PAL, conversation, and selected face. This quick setup does not gather an interview or run the guided PAL Maker build and verification pipeline; use it only when the creator hands over a finished system prompt and asks to skip the build, and otherwise use tavus_pal_build_and_verify.",
     {
       system_prompt: z.string().min(1),
       pal_name: z.string().default("Agentic Tavus PAL"),
@@ -1835,8 +1844,13 @@ export function createTavusMcpServer(
 
   server.tool(
     "tavus_pal_build_and_verify",
-    "Build and publish a PAL through the guided PAL Maker pipeline from a completed brief and optional interview Q&A. Drafts the personality, objectives, guardrails, and greeting, selects a face, publishes the PAL, runs conversation probes, and returns the PAL ID, editor URL, and judged verification result. The briefs fields describe each artifact, including knowledge, tools, skills, perception, and face preferences. Connected tools or knowledge sources may access external services during building or testing. Usually takes one to three minutes.",
+    "The standard way to build a PAL. Builds and publishes a PAL through the guided PAL Maker pipeline that Charlie uses, from a completed brief and optional interview Q&A. Drafts the personality, objectives, guardrails, and greeting, selects a face, publishes the PAL, runs conversation probes, and returns the PAL ID, editor URL, and judged verification result. The briefs fields describe each artifact, including knowledge, tools, skills, perception, and face preferences. Connected tools or knowledge sources may access external services during building or testing. Usually takes one to three minutes.\n\nTo change an existing PAL, pass its pal_id, put the requested change in prompt, and fill only the briefs for the parts that should change. The same PAL Maker drafters edit the PAL and leave the other parts alone. Put built-in capabilities in briefs.skills: on-screen scorecards, quizzes, forms, and charts (Magic Canvas), web search, memory, and slide decks. Use briefs.tools only for an external action such as a webhook or API call. The PAL keeps its face unless face_id is given. The change is published, together with any unpublished PAL Maker edits on that PAL.",
     {
+      pal_id: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("An existing PAL to change instead of building a new one."),
       prompt: z.string().min(1),
       interview: z
         .array(z.object({ question: z.string(), answer: z.string() }))
@@ -1860,9 +1874,10 @@ export function createTavusMcpServer(
       probes: z.array(z.string()).max(5).optional(),
     },
     writeAnnotations("Build and verify PAL with PAL Maker", { destructiveHint: true, openWorldHint: true }),
-    async ({ prompt, interview, briefs, face_id, pal_name, probes }) =>
+    async ({ pal_id, prompt, interview, briefs, face_id, pal_name, probes }) =>
       toolResult(
         await runGuidedBuild(client, config.palMakerUrl, {
+          pal_id,
           prompt,
           interview,
           briefs,
@@ -2756,6 +2771,7 @@ export interface InterviewEntry {
 }
 
 export interface GuidedBuildOptions {
+  pal_id?: string;
   prompt: string;
   interview?: InterviewEntry[];
   briefs?: Partial<Record<DraftBriefKey, string>>;
@@ -2784,12 +2800,16 @@ export function interviewMessages(
 
 export function draftBriefs(
   briefs: Partial<Record<DraftBriefKey, string>> | undefined,
+  editing = false,
 ): Record<string, string> {
-  // The four core artifacts are always drafted so a sparse agent-supplied
-  // brief set cannot produce a PAL missing objectives or guardrails.
+  // A new PAL always drafts the four core artifacts so a sparse agent-supplied
+  // brief set cannot produce a PAL missing objectives or guardrails. An edit
+  // runs only the briefed drafters, so the rest of the PAL stays as it is.
   const mapped: Record<string, string> = {};
-  for (const key of DRAFT_CORE_ARTIFACTS) {
-    mapped[key] = DRAFT_FALLBACK_BRIEF;
+  if (!editing) {
+    for (const key of DRAFT_CORE_ARTIFACTS) {
+      mapped[key] = DRAFT_FALLBACK_BRIEF;
+    }
   }
   for (const key of DRAFT_BRIEF_KEYS) {
     const value = briefs?.[key];
@@ -3015,8 +3035,24 @@ async function runGuidedBuild(
     }
   }
 
-  const sessionName = options.pal_name?.trim() || derivePalName(prompt);
-  const session = expectObject(await client.post("builder", { name: sessionName }));
+  const editPalId = options.pal_id?.trim();
+  const briefs = draftBriefs(options.briefs, Boolean(editPalId));
+  if (editPalId && !Object.keys(briefs).length) {
+    throw new Error(
+      "Changing an existing PAL needs at least one brief naming what to change, " +
+        "for example briefs.skills for an on-screen scorecard or briefs.personality for prompt wording.",
+    );
+  }
+  let sessionName = options.pal_name?.trim();
+  if (editPalId && !sessionName) {
+    const existing = expectObject(await client.get("pals", editPalId));
+    sessionName = String(existing.pal_name ?? existing.persona_name ?? "").trim();
+  }
+  // RQH opens the session on the PAL's private PAL Maker draft when it has
+  // one; that row takes the edits and publish copies them onto the live PAL.
+  const session = expectObject(
+    await client.post("builder", clean({ name: sessionName || derivePalName(prompt), persona_id: editPalId })),
+  );
   const builderId = String(session.builder_id ?? "");
   let palId = String(session.persona_id ?? "");
   if (!builderId || !palId) {
@@ -3030,7 +3066,7 @@ async function runGuidedBuild(
   const current = expectObject(await client.get("pals", palId, { include_settings: "true" }));
   const terminal = await client.postNdjson(`builder/${builderId}/draft-fanout`, {
     message: prompt,
-    briefs: draftBriefs(options.briefs),
+    briefs,
     current: {
       system_prompt: current.system_prompt ?? "",
       greeting: current.greeting ?? "",
@@ -3045,8 +3081,10 @@ async function runGuidedBuild(
   if (operations.length) {
     await client.patch("pals", palId, operations);
   }
+  const builtinChanges = await applyBuiltinRecommendations(client, palId, content.tools);
 
-  await client.post(`builder/${builderId}/publish`, {});
+  const published = expectObject(await client.post(`builder/${builderId}/publish`, {}));
+  palId = String(published.persona_id ?? session.live_persona_id ?? palId);
 
   let faceSelection: Record<string, unknown> | null = null;
   let faceId = options.face_id;
@@ -3054,7 +3092,7 @@ async function runGuidedBuild(
     await client.patch("pals", palId, [
       { op: "replace", path: "/default_face_id", value: faceId },
     ]);
-  } else {
+  } else if (!editPalId) {
     faceSelection = expectObject(
       await client.post("persona-builder/select-replica", { persona_id: palId }),
     );
@@ -3111,6 +3149,11 @@ async function runGuidedBuild(
     face_id: faceId ?? spec.default_replica_id,
     face_selection: faceSelection,
     pal_spec: spec,
+    drafted: Object.keys(content).filter((kind) => {
+      const value = content[kind];
+      return value != null && !(isRecord(value) && (value.error || value.status === "superseded"));
+    }),
+    builtin_changes: builtinChanges,
     probes,
     smoke_transcript: smokeTranscript,
     verdict,
@@ -3118,6 +3161,50 @@ async function runGuidedBuild(
   };
 }
 
+// RQH's tools drafter only recommends built-in capabilities: the client that
+// asked for the draft attaches them, as the portal does for Charlie.
+async function applyBuiltinRecommendations(
+  client: TavusApiClient,
+  palId: string,
+  tools: unknown,
+): Promise<string[]> {
+  if (!isRecord(tools) || tools.error || tools.status === "superseded") {
+    return [];
+  }
+  const attach = stringArray(tools.attach_builtins);
+  const detach = stringArray(tools.detach_builtins);
+  if (!attach.length && !detach.length) {
+    return [];
+  }
+  // Read after the fan-out: the skills drafter may have attached and
+  // configured the same capability, and an empty attach would reset it.
+  const attached = skillMap(await client.getPath(`pals/${palId}/skills/`));
+  const changes: string[] = [];
+  for (const [builtin, attaching] of [
+    ...attach.map((id) => [id, true] as const),
+    ...detach.map((id) => [id, false] as const),
+  ]) {
+    const capability = CAPABILITY_ALIASES[builtin];
+    const skillId = capability ? CAPABILITY_CATALOG[capability].rqh_skill_id : null;
+    if (!capability || !skillId || attaching === (skillId in attached)) {
+      continue;
+    }
+    if (attaching && capability === "slide_presenter") {
+      changes.push(
+        "slide_presenter recommended but not attached: attach it with tavus_pal_capability_attach and the deck's document_ids.",
+      );
+      continue;
+    }
+    if (attaching) {
+      await client.put(`pals/${palId}/skills/${skillId}`, { config: {} });
+    } else {
+      await client.deletePath(`pals/${palId}/skills/${skillId}`);
+    }
+    changes.push(`${attaching ? "attached" : "detached"} ${capability}`);
+  }
+  return changes;
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }