Merge branch 'main' into claude/objective-cohen-fb1f7d

Three conflicts, all additive collisions in lists main also grew:

- `ARCHITECTURE.md`: main added `thread_agent_kwargs`, `a2ui` and
  `url_fetch_policy` rows to the Python config table. Kept all of them and
  reinserted `template_tools_provider` after `session_manager_provider`.
- `python/README.md`: main expanded the Key Files table with five more
  modules. Kept them and reinserted `template_tools.py` beside
  `client_proxy_tool.py`, the other module that syncs the tool registry.
- `typescript/src/__tests__/exports.test.ts`: main appended
  `DEFAULT_URL_FETCH_POLICY` and `UrlFetchPolicyError` to the expected export
  list. Kept both alongside `syncTemplateTools` and `parkedBatchToolNames`.

`error-codes.json` merged clean and stayed alphabetical:
`TEMPLATE_TOOLS_PROVIDER_ERROR` sits before `THREAD_AGENT_CONFIG_ERROR`, and
main's new `URL_FETCH_POLICY_INVALID` last. Both READMEs' new "Terminal error
codes" sections point at that file and enumerate only the divergences, so a
shared code carrying a byte-identical template on both sides needs no entry
there.

Nothing in main's token-usage or URL-fetch-policy work touches the request
path this branch adds, and the per-request template-tools sync still sits
between the interrupt-session gate and the proxy sync on both sides.

Verified after the merge: 1356 passed / 1 skipped (Python), 1714 passed
(TypeScript), 78 passed (TypeScript examples), `tsc --noEmit` clean.

Author: ranst91

apps/dojo/package.json

@@ -11,7 +11,8 @@
     "generate-content-json": "npx tsx scripts/generate-content-json.ts",
     "test:crewai-config": "tsx --test src/crewai.test.ts",
     "run-everything": "./scripts/prep-dojo-everything.js && ./scripts/run-dojo-everything.js",
-    "local-install": "bash scripts/local-install.sh"
+    "local-install": "bash scripts/local-install.sh",
+    "test:a2ui-config": "tsx --test src/a2ui-config.test.ts"
   },
   "dependencies": {
     "@a2a-js/sdk": "0.2.5",
@@ -91,7 +92,8 @@
     "tailwindcss-animate": "^1.0.7",
     "untruncate-json": "^0.0.1",
     "uuid": "^11.1.0",
-    "zod": "^3.25.75"
+    "zod": "^3.25.75",
+    "zod-to-json-schema": "3.25.2"
   },
   "peerDependencies": {
     "@ag-ui/client": "workspace:*",

apps/dojo/src/a2ui-config.test.ts

@@ -0,0 +1,92 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  AbstractAgent,
+  type BaseEvent,
+  EventType,
+  type RunAgentInput,
+} from "@ag-ui/client";
+import {
+  A2UIMiddleware,
+  A2UI_SCHEMA_CONTEXT_DESCRIPTION,
+} from "@ag-ui/a2ui-middleware";
+import { Observable, firstValueFrom, toArray } from "rxjs";
+
+import { dynamicSchemaCatalog } from "./a2ui-catalog";
+import { DOJO_A2UI_MIDDLEWARE_CONFIG } from "./a2ui-config";
+
+class CaptureAgent extends AbstractAgent {
+  readonly runCalls: RunAgentInput[] = [];
+
+  run(input: RunAgentInput): Observable<BaseEvent> {
+    this.runCalls.push(input);
+    return new Observable((subscriber) => {
+      subscriber.next({
+        type: EventType.RUN_STARTED,
+        threadId: input.threadId,
+        runId: input.runId,
+      });
+      subscriber.next({
+        type: EventType.RUN_FINISHED,
+        threadId: input.threadId,
+        runId: input.runId,
+      });
+      subscriber.complete();
+    });
+  }
+}
+
+test("Dojo A2UI middleware forwards the rendered dynamic catalog", async () => {
+  const downstream = new CaptureAgent();
+  const middleware = new A2UIMiddleware(DOJO_A2UI_MIDDLEWARE_CONFIG);
+
+  await firstValueFrom(
+    middleware
+      .run(
+        {
+          threadId: "test-thread",
+          runId: "test-run",
+          tools: [],
+          context: [],
+          forwardedProps: {},
+          state: {},
+          messages: [],
+        },
+        downstream,
+      )
+      .pipe(toArray()),
+  );
+
+  assert.equal(downstream.runCalls.length, 1);
+  const forwarded = downstream.runCalls[0];
+  const schemaContext = forwarded.context.find(
+    ({ description }) => description === A2UI_SCHEMA_CONTEXT_DESCRIPTION,
+  );
+  assert.ok(
+    schemaContext && typeof schemaContext.value === "string",
+    "dynamic catalog schema must reach downstream agent context",
+  );
+
+  const schema = JSON.parse(schemaContext.value) as {
+    catalogId: string;
+    components: Record<
+      string,
+      { allOf?: Array<{ properties?: Record<string, unknown> }> }
+    >;
+  };
+  assert.equal(schema.catalogId, dynamicSchemaCatalog.id);
+  assert.deepEqual(Object.keys(schema.components), [
+    ...dynamicSchemaCatalog.components.keys(),
+  ]);
+
+  const hotelProperties = schema.components.HotelCard.allOf?.find(
+    ({ properties }) => properties,
+  )?.properties;
+  assert.ok(hotelProperties);
+  assert.ok("pricePerNight" in hotelProperties);
+  const rating = hotelProperties.rating as {
+    anyOf?: Array<{ type?: string }>;
+  };
+  assert.ok(rating.anyOf?.some(({ type }) => type === "number"));
+});

apps/dojo/src/a2ui-config.ts

@@ -0,0 +1,53 @@
+import type { A2UIMiddlewareConfig } from "@ag-ui/a2ui-middleware";
+import { zodToJsonSchema } from "zod-to-json-schema";
+
+import {
+  HotelCardApi,
+  ProductCardApi,
+  RowApi,
+  TeamMemberCardApi,
+} from "./a2ui-catalog/apis";
+
+const DOJO_A2UI_CATALOG_ID = "https://a2ui.org/demos/dojo/dynamic_catalog.json";
+
+const dynamicComponentApis = [
+  RowApi,
+  HotelCardApi,
+  ProductCardApi,
+  TeamMemberCardApi,
+];
+
+const components = Object.fromEntries(
+  dynamicComponentApis.map((componentApi) => {
+    const schema = zodToJsonSchema(componentApi.schema, {
+      target: "jsonSchema2019-09",
+    }) as {
+      properties?: Record<string, unknown>;
+      required?: string[];
+    };
+    return [
+      componentApi.name,
+      {
+        allOf: [
+          { $ref: "common_types.json#/$defs/ComponentCommon" },
+          {
+            properties: {
+              component: { const: componentApi.name },
+              ...(schema.properties ?? {}),
+            },
+            required: ["component", ...(schema.required ?? [])],
+          },
+        ],
+      },
+    ];
+  }),
+);
+
+export const DOJO_A2UI_MIDDLEWARE_CONFIG = {
+  injectA2UITool: true,
+  defaultCatalogId: DOJO_A2UI_CATALOG_ID,
+  schema: {
+    catalogId: DOJO_A2UI_CATALOG_ID,
+    components,
+  },
+} satisfies A2UIMiddlewareConfig;

apps/dojo/src/agents.ts

@@ -44,17 +44,14 @@ import { Ag2Agent } from "@ag-ui/ag2";
 import { LangroidHttpAgent } from "@ag-ui/langroid";
 import { WatsonxAgent } from "@ag-ui/watsonx";
 import { A2UIMiddleware } from "@ag-ui/a2ui-middleware";
+import { DOJO_A2UI_MIDDLEWARE_CONFIG } from "./a2ui-config";
 import {
   CREWAI_CONVERSATIONAL_AGENT_PATHS,
   CREWAI_FLOW_AGENT_PATHS,
 } from "./crewai";
 
 const envVars = getEnvVars();
 
-// Catalog the dojo's dynamic A2UI demos render against (HotelCard / ProductCard
-// / TeamMemberCard / Row).
-const A2UI_DOJO_CATALOG_ID = "https://a2ui.org/demos/dojo/dynamic_catalog.json";
-
 // Per-agent A2UI inject whitelist for the adk-middleware integration. These
 // subagent demos wire no a2ui tool themselves and rely on the adapter
 // auto-injecting `generate_a2ui` when it sees `injectA2UITool`. Injection is
@@ -101,10 +98,7 @@ function createCrewAIIntegrationAgents<const T extends Record<string, string>>(
   );
   for (const id of CREWAI_A2UI_INJECT_AGENTS) {
     (agents as Record<string, AbstractAgent>)[id]?.use(
-      new A2UIMiddleware({
-        injectA2UITool: true,
-        defaultCatalogId: A2UI_DOJO_CATALOG_ID,
-      }),
+      new A2UIMiddleware(DOJO_A2UI_MIDDLEWARE_CONFIG),
     );
   }
   return agents;
@@ -155,10 +149,7 @@ export const agentsIntegrations = {
     // Whitelist-driven per-agent A2UI injection (see ADK_A2UI_INJECT_AGENTS).
     for (const id of ADK_A2UI_INJECT_AGENTS) {
       (agents as Record<string, AbstractAgent>)[id]?.use(
-        new A2UIMiddleware({
-          injectA2UITool: true,
-          defaultCatalogId: A2UI_DOJO_CATALOG_ID,
-        }),
+        new A2UIMiddleware(DOJO_A2UI_MIDDLEWARE_CONFIG),
       );
     }
     return agents;
@@ -620,10 +611,7 @@ export const agentsIntegrations = {
     };
     for (const id of STRANDS_A2UI_INJECT_AGENTS) {
       (agents as Record<string, AbstractAgent>)[id]?.use(
-        new A2UIMiddleware({
-          injectA2UITool: true,
-          defaultCatalogId: A2UI_DOJO_CATALOG_ID,
-        }),
+        new A2UIMiddleware(DOJO_A2UI_MIDDLEWARE_CONFIG),
       );
     }
     return agents;
@@ -669,10 +657,7 @@ export const agentsIntegrations = {
     };
     for (const id of STRANDS_A2UI_INJECT_AGENTS) {
       (agents as Record<string, AbstractAgent>)[id]?.use(
-        new A2UIMiddleware({
-          injectA2UITool: true,
-          defaultCatalogId: A2UI_DOJO_CATALOG_ID,
-        }),
+        new A2UIMiddleware(DOJO_A2UI_MIDDLEWARE_CONFIG),
       );
     }
     return agents;