@codemation/core-nodes 0.4.3 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codemation/core-nodes",
-  "version": "0.4.3",
+  "version": "0.6.0",
   "publishConfig": {
     "access": "public"
   },
@@ -28,10 +28,12 @@
     }
   },
   "dependencies": {
-    "@langchain/core": "^1.1.31",
-    "@langchain/openai": "^1.2.12",
+    "@ai-sdk/openai": "^3.0.53",
+    "@ai-sdk/provider": "^3.0.8",
+    "ai": "^6.0.168",
+    "croner": "^10.0.1",
     "lucide-react": "^0.577.0",
-    "@codemation/core": "0.8.1"
+    "@codemation/core": "0.10.0"
   },
   "devDependencies": {
     "@types/node": "^25.3.5",
@@ -49,6 +51,7 @@
     "build": "tsdown",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "lint": "eslint .",
-    "test": "pnpm --filter @codemation/core build && pnpm build && vitest run"
+    "test": "pnpm --filter @codemation/core build && pnpm build && vitest run",
+    "test:unit": "vitest run"
   }
 }

package/src/authoring/defineRestNode.types.ts

@@ -0,0 +1,204 @@
+import { defineNode } from "@codemation/core";
+import type { DefinedNode, DefinedNodeCredentialBindings } from "@codemation/core";
+import type { ZodType } from "zod";
+import type { HttpBodySpec } from "../http/httpRequest.types";
+import { HttpRequestExecutor } from "../http/HttpRequestExecutor";
+import { HttpBodyBuilder } from "../http/HttpBodyBuilder";
+import { HttpUrlBuilder } from "../http/HttpUrlBuilder";
+
+type MaybePromise<T> = T | Promise<T>;
+
+/**
+ * API endpoint descriptor.
+ */
+export type RestNodeApi = Readonly<{
+  /**
+   * Base URL, e.g. `"https://api.slack.com"`.
+   */
+  baseUrl: string;
+  /**
+   * Path relative to `baseUrl`. May contain `{paramName}` placeholders that
+   * are substituted from `input` keys before the request is made.
+   * Example: `"/users/{userId}/profile"`
+   */
+  path: string;
+  /** HTTP method (default: GET). */
+  method?: string;
+}>;
+
+/**
+ * The HTTP result shape passed into the `response` mapper.
+ */
+export type RestNodeResponseContext = Readonly<{
+  status: number;
+  ok: boolean;
+  statusText: string;
+  mimeType: string;
+  headers: Readonly<Record<string, string>>;
+  json?: unknown;
+  text?: string;
+}>;
+
+/**
+ * What the `request` callback may return to customise the request.
+ */
+export type RestNodeRequestShape = Readonly<{
+  /** Additional path parameters to substitute (merged with `input`). */
+  pathParams?: Readonly<Record<string, string>>;
+  /** Extra query params. */
+  query?: Readonly<Record<string, string>>;
+  /** Extra headers. */
+  headers?: Readonly<Record<string, string>>;
+  /** Request body. */
+  body?: HttpBodySpec;
+}>;
+
+/**
+ * Error handling policy for non-2xx responses.
+ *  - `"throw"` (default) — throws an `Error` for non-2xx responses.
+ *  - `"passthrough"` — returns the result regardless of status.
+ */
+export type RestNodeErrorPolicy = "throw" | "passthrough";
+
+export interface DefineRestNodeOptions<
+  TKey extends string,
+  TCredentials extends DefinedNodeCredentialBindings | undefined,
+  TInputJson,
+  TOutputJson,
+> {
+  readonly key: TKey;
+  readonly title: string;
+  readonly description?: string;
+  readonly icon?: string;
+  readonly api: RestNodeApi;
+  /**
+   * Credential bindings keyed by slot. Use the built-in credential types from
+   * `@codemation/core-nodes` (e.g. `bearerTokenCredentialType`) or any custom one.
+   * The slot key must match what the `request` callback's context uses.
+   */
+  readonly credentials?: TCredentials;
+  /**
+   * Zod schema for per-item input. Validated before `execute`.
+   */
+  readonly inputSchema?: ZodType<TInputJson>;
+  /**
+   * Builds the per-request customisations from the item input.
+   * Return `body`, `query`, `headers`, and/or `pathParams`.
+   */
+  request?(context: Readonly<{ input: TInputJson }>): MaybePromise<RestNodeRequestShape>;
+  /**
+   * Maps the HTTP response to the node's output JSON.
+   * When omitted, the output is `{ status, ok, statusText, mimeType, headers, json, text }`.
+   */
+  response?(context: RestNodeResponseContext & Readonly<{ input: TInputJson }>): MaybePromise<TOutputJson>;
+  /**
+   * How to handle non-2xx responses.
+   * @default "throw"
+   */
+  readonly errorPolicy?: RestNodeErrorPolicy;
+}
+
+/**
+ * Substitutes `{name}` placeholders in a path template using values from `params`.
+ */
+function substitutePath(template: string, params: Readonly<Record<string, unknown>>): string {
+  return template.replace(/\{([^}]+)}/g, (_match, key: string) => {
+    const value = params[key];
+    return value !== undefined ? String(value) : `{${key}}`;
+  });
+}
+
+/**
+ * Declarative helper for creating thin API-wrapper nodes.
+ *
+ * Usage:
+ * ```ts
+ * export const postMessage = defineRestNode({
+ *   key: "slack.post-message",
+ *   title: "Send Slack message",
+ *   icon: "si:slack",
+ *   api: { baseUrl: "https://slack.com/api", path: "/chat.postMessage", method: "POST" },
+ *   credentials: { auth: bearerTokenCredentialType },
+ *   inputSchema: z.object({ channel: z.string(), text: z.string() }),
+ *   request: ({ input }) => ({
+ *     body: { kind: "json", data: { channel: input.channel, text: input.text } },
+ *   }),
+ *   response: ({ json }) => ({ messageTs: (json as any).ts }),
+ * });
+ * ```
+ *
+ * - `defineRestNode` is a thin wrapper over `defineNode`; it does not introduce a new runtime kind.
+ * - Credential sessions are resolved via the `credentials` binding map (same as `defineNode`).
+ * - Path `{placeholder}` substitution is applied from `input` keys before the request is made.
+ * - Non-2xx responses throw an `Error` by default (`errorPolicy: "throw"`).
+ */
+export function defineRestNode<
+  TKey extends string,
+  TCredentials extends DefinedNodeCredentialBindings | undefined,
+  TInputJson,
+  TOutputJson = RestNodeResponseContext,
+>(
+  options: DefineRestNodeOptions<TKey, TCredentials, TInputJson, TOutputJson>,
+): DefinedNode<TKey, Record<string, never>, TInputJson, TOutputJson, TCredentials> {
+  const errorPolicy = options.errorPolicy ?? "throw";
+
+  return defineNode<TKey, Record<string, never>, TInputJson, TOutputJson, TCredentials>({
+    key: options.key,
+    title: options.title,
+    description: options.description,
+    icon: options.icon,
+    credentials: options.credentials,
+    inputSchema: options.inputSchema,
+    async execute({ input, item, ctx }, { credentials }) {
+      // Resolve credential if one is bound.
+      const credentialSlot = options.credentials ? Object.keys(options.credentials)[0] : undefined;
+      const credential = credentialSlot
+        ? await (credentials as Record<string, () => Promise<unknown>>)[credentialSlot]?.()
+        : undefined;
+
+      // Build path by substituting `{name}` placeholders from input.
+      const inputRecord = (input as Record<string, unknown>) ?? {};
+      const requestShape = options.request ? await options.request({ input }) : {};
+      const pathParams = { ...inputRecord, ...(requestShape.pathParams ?? {}) };
+      const resolvedPath = substitutePath(options.api.path, pathParams);
+      const resolvedUrl = `${options.api.baseUrl}${resolvedPath}`;
+
+      const executor = new HttpRequestExecutor(globalThis.fetch, new HttpBodyBuilder(), new HttpUrlBuilder());
+      const result = await executor.execute(
+        {
+          url: resolvedUrl,
+          method: (options.api.method ?? "GET").toUpperCase(),
+          headers: requestShape.headers,
+          query: requestShape.query,
+          body: requestShape.body,
+          credential: credential as Parameters<typeof executor.execute>[0]["credential"],
+          ctx: ctx as unknown as Parameters<typeof executor.execute>[0]["ctx"],
+        },
+        item,
+      );
+
+      if (errorPolicy === "throw" && !result.ok) {
+        throw new Error(`HTTP ${result.status} ${result.statusText} for ${result.method} ${result.url}`);
+      }
+
+      const responseCtx: RestNodeResponseContext = {
+        status: result.status,
+        ok: result.ok,
+        statusText: result.statusText,
+        mimeType: result.mimeType,
+        headers: result.headers,
+        ...(result.json !== undefined ? { json: result.json } : {}),
+        ...(result.text !== undefined ? { text: result.text } : {}),
+      };
+
+      if (options.response) {
+        return await options.response({ ...responseCtx, input });
+      }
+
+      // Wrap in `{ json: ... }` so the engine's Item-shape detection unwraps once
+      // and the response context becomes the item's payload as-is (preserving the
+      // inner `json` field on the response for callers).
+      return { json: responseCtx } as unknown as TOutputJson;
+    },
+  }) as unknown as DefinedNode<TKey, Record<string, never>, TInputJson, TOutputJson, TCredentials>;
+}

package/src/chatModels/OpenAIChatModelFactory.ts

@@ -1,6 +1,8 @@
-import type { ChatModelFactory, LangChainChatModelLike, NodeExecutionContext } from "@codemation/core";
+import type { ChatLanguageModel, ChatModelFactory, NodeExecutionContext } from "@codemation/core";
 import { chatModel } from "@codemation/core";
-import { ChatOpenAI } from "@langchain/openai";
+
+import { createOpenAI } from "@ai-sdk/openai";
+
 import type { OpenAiCredentialSession } from "./OpenAiCredentialSession";
 import type { OpenAIChatModelConfig } from "./openAiChatModelConfig";
 
@@ -8,14 +10,21 @@ import type { OpenAIChatModelConfig } from "./openAiChatModelConfig";
 export class OpenAIChatModelFactory implements ChatModelFactory<OpenAIChatModelConfig> {
   async create(
     args: Readonly<{ config: OpenAIChatModelConfig; ctx: NodeExecutionContext<any> }>,
-  ): Promise<LangChainChatModelLike> {
+  ): Promise<ChatLanguageModel> {
     const session = await args.ctx.getCredential<OpenAiCredentialSession>(args.config.credentialSlotKey);
-    return new ChatOpenAI({
+    const provider = createOpenAI({
       apiKey: session.apiKey,
-      model: args.config.model,
-      temperature: args.config.options?.temperature,
-      maxTokens: args.config.options?.maxTokens,
-      configuration: session.baseUrl ? { baseURL: session.baseUrl } : undefined,
+      baseURL: session.baseUrl,
     });
+    const languageModel = provider.chat(args.config.model);
+    return {
+      languageModel,
+      modelName: args.config.model,
+      provider: "openai",
+      defaultCallOptions: {
+        maxOutputTokens: args.config.options?.maxTokens,
+        temperature: args.config.options?.temperature,
+      },
+    };
   }
 }

package/src/chatModels/OpenAiStrictJsonSchemaFactory.ts

@@ -0,0 +1,123 @@
+import type { ZodSchemaAny } from "@codemation/core";
+import { inject, injectable } from "@codemation/core";
+
+import { AIAgentExecutionHelpersFactory } from "../nodes/AIAgentExecutionHelpersFactory";
+
+/**
+ * Produces an OpenAI **strict mode**–compliant JSON Schema for an AIAgent `outputSchema`.
+ *
+ * Why this exists: AI SDK's default Zod → JSON Schema conversion (Zod v4's `toJSONSchema`) can
+ * emit `unevaluatedProperties: false` or skip `additionalProperties: false` on object branches.
+ * OpenAI's strict-mode validator rejects anything missing `additionalProperties: false` at
+ * `context=()` (the root) and requires **all properties** in `required`. We convert here so all
+ * legal Zod root shapes work (object, union, discriminated union, nullable-object wrapper, array,
+ * intersection, …) and hand AI SDK a pre-tagged `jsonSchema(...)` record that passes straight
+ * through to the provider.
+ *
+ * Rules enforced on the produced JSON Schema record:
+ * - Every `type: "object"` node (root and nested under `allOf`/`anyOf`/`oneOf`/`items`/`prefixItems`/`$defs`):
+ *   - `additionalProperties: false`
+ *   - `required` lists **every** key in `properties` (OpenAI strict requires all properties required;
+ *     express optionality via `.nullable()` / `z.union([..., z.null()])`).
+ *   - `properties` is always an object (empty object allowed).
+ * - `$schema`, `unevaluatedProperties`, and `default` are stripped (OpenAI rejects / ignores them).
+ * - `sanitizeJsonSchemaRequiredKeywordsForCfworker` invariants from
+ *   {@link AIAgentExecutionHelpersFactory.createJsonSchemaRecord} are preserved as a starting point.
+ */
+@injectable()
+export class OpenAiStrictJsonSchemaFactory {
+  constructor(
+    @inject(AIAgentExecutionHelpersFactory)
+    private readonly executionHelpers: AIAgentExecutionHelpersFactory,
+  ) {}
+
+  createStructuredOutputRecord(
+    schema: ZodSchemaAny,
+    options: Readonly<{ schemaName: string; title?: string }>,
+  ): Record<string, unknown> {
+    const record = this.executionHelpers.createJsonSchemaRecord(schema, {
+      schemaName: options.schemaName,
+      requireObjectRoot: false,
+    });
+    this.strictifyRecursive(record);
+    if (options.title !== undefined) {
+      record.title = options.title;
+    }
+    return record;
+  }
+
+  private strictifyRecursive(node: unknown): void {
+    if (!node || typeof node !== "object" || Array.isArray(node)) {
+      return;
+    }
+    const o = node as Record<string, unknown>;
+    this.stripOpenAiRejectedKeywords(o);
+    if (this.isObjectNode(o)) {
+      const props = this.readPropertiesObject(o);
+      o.properties = props;
+      o.additionalProperties = false;
+      o.required = Object.keys(props);
+      for (const value of Object.values(props)) {
+        this.strictifyRecursive(value);
+      }
+    }
+    this.recurseIntoComposites(o);
+  }
+
+  private stripOpenAiRejectedKeywords(o: Record<string, unknown>): void {
+    delete o["$schema"];
+    delete o["unevaluatedProperties"];
+    delete o["default"];
+  }
+
+  private isObjectNode(o: Record<string, unknown>): boolean {
+    const typeIsObject =
+      o.type === "object" || (Array.isArray(o.type) && (o.type as ReadonlyArray<unknown>).includes("object"));
+    const hasObjectProperties =
+      o.properties !== undefined && typeof o.properties === "object" && !Array.isArray(o.properties);
+    return typeIsObject || hasObjectProperties;
+  }
+
+  private readPropertiesObject(o: Record<string, unknown>): Record<string, unknown> {
+    if (o.properties && typeof o.properties === "object" && !Array.isArray(o.properties)) {
+      return o.properties as Record<string, unknown>;
+    }
+    return {};
+  }
+
+  private recurseIntoComposites(o: Record<string, unknown>): void {
+    for (const key of ["allOf", "anyOf", "oneOf", "prefixItems"] as const) {
+      const branch = o[key];
+      if (Array.isArray(branch)) {
+        for (const sub of branch) {
+          this.strictifyRecursive(sub);
+        }
+      }
+    }
+    if (o.not) {
+      this.strictifyRecursive(o.not);
+    }
+    if (o.items) {
+      if (Array.isArray(o.items)) {
+        for (const sub of o.items) {
+          this.strictifyRecursive(sub);
+        }
+      } else {
+        this.strictifyRecursive(o.items);
+      }
+    }
+    for (const key of ["if", "then", "else"] as const) {
+      if (o[key]) {
+        this.strictifyRecursive(o[key]);
+      }
+    }
+    for (const key of ["$defs", "definitions"] as const) {
+      const defs = o[key];
+      if (defs && typeof defs === "object" && !Array.isArray(defs)) {
+        for (const sub of Object.values(defs as Record<string, unknown>)) {
+          this.strictifyRecursive(sub);
+        }
+      }
+    }
+  }
+}

package/src/credentials/ApiKeyCredentialType.ts

@@ -0,0 +1,60 @@
+import { defineCredential } from "@codemation/core";
+import type { CredentialSession, HttpCredentialDelta } from "../http/httpRequest.types";
+
+/**
+ * API key credential that injects a key either as an HTTP header or a query parameter.
+ */
+export const apiKeyCredentialType = defineCredential({
+  key: "core-nodes.api-key",
+  label: "API Key",
+  description: "Authenticates requests by injecting an API key into a header or query parameter.",
+  public: {
+    placement: {
+      label: "Placement",
+      type: "string",
+      helpText: 'Where to send the key: "header" (default) or "query".',
+      placeholder: "header",
+    },
+    name: {
+      label: "Parameter name",
+      type: "string",
+      helpText: 'Header or query param name. Defaults to "X-API-Key" for headers, "api_key" for query.',
+      placeholder: "X-API-Key",
+    },
+  },
+  secret: {
+    apiKey: {
+      label: "API Key",
+      type: "password",
+      required: true,
+      helpText: "The secret API key value.",
+    },
+  },
+  async createSession(args): Promise<CredentialSession> {
+    const apiKey = String(args.material.apiKey ?? "");
+    if (!apiKey) {
+      throw new Error("API key credential material is incomplete: apiKey is required.");
+    }
+    const placement = String(args.publicConfig.placement ?? "header").toLowerCase();
+    const isQuery = placement === "query";
+    const defaultName = isQuery ? "api_key" : "X-API-Key";
+    const paramName = String(args.publicConfig.name ?? "").trim() || defaultName;
+
+    return {
+      applyToRequest: (_spec): HttpCredentialDelta => {
+        if (isQuery) {
+          return { query: { [paramName]: apiKey } };
+        }
+        return { headers: { [paramName]: apiKey } };
+      },
+    };
+  },
+  async test(args) {
+    const apiKey = String(args.material.apiKey ?? "");
+    return {
+      status: apiKey.length > 0 ? "healthy" : "failing",
+      message: apiKey.length > 0 ? "API key is configured." : "API key is missing.",
+      testedAt: new Date().toISOString(),
+    };
+  },
+});

package/src/credentials/BasicAuthCredentialType.ts

@@ -0,0 +1,51 @@
+import { defineCredential } from "@codemation/core";
+import type { CredentialSession, HttpCredentialDelta } from "../http/httpRequest.types";
+
+/**
+ * HTTP Basic authentication credential.
+ * Session sets `Authorization: Basic <base64(username:password)>`.
+ */
+export const basicAuthCredentialType = defineCredential({
+  key: "core-nodes.basic-auth",
+  label: "Basic Auth",
+  description: "Authenticates requests using HTTP Basic Authentication (username + password).",
+  public: {
+    username: {
+      label: "Username",
+      type: "string",
+      required: true,
+      helpText: "The username for HTTP Basic Authentication.",
+    },
+  },
+  secret: {
+    password: {
+      label: "Password",
+      type: "password",
+      required: true,
+      helpText: "The password for HTTP Basic Authentication.",
+    },
+  },
+  async createSession(args): Promise<CredentialSession> {
+    const username = String(args.publicConfig.username ?? "");
+    const password = String(args.material.password ?? "");
+    if (!username) {
+      throw new Error("Basic Auth credential is incomplete: username is required.");
+    }
+    const encoded = Buffer.from(`${username}:${password}`).toString("base64");
+    return {
+      applyToRequest: (_spec): HttpCredentialDelta => ({
+        headers: { authorization: `Basic ${encoded}` },
+      }),
+    };
+  },
+  async test(args) {
+    const username = String(args.publicConfig.username ?? "");
+    const password = String(args.material.password ?? "");
+    const ok = username.length > 0 && password.length > 0;
+    return {
+      status: ok ? "healthy" : "failing",
+      message: ok ? "Basic Auth credentials are configured." : "Username or password is missing.",
+      testedAt: new Date().toISOString(),
+    };
+  },
+});

package/src/credentials/BearerTokenCredentialType.ts

@@ -0,0 +1,40 @@
+import { defineCredential } from "@codemation/core";
+import type { CredentialSession, HttpCredentialDelta } from "../http/httpRequest.types";
+
+/**
+ * Simple Bearer token credential.
+ * Session sets `Authorization: Bearer <token>` on every request.
+ */
+export const bearerTokenCredentialType = defineCredential({
+  key: "core-nodes.bearer-token",
+  label: "Bearer Token",
+  description: "Authenticates requests using a static Bearer token in the Authorization header.",
+  public: {},
+  secret: {
+    token: {
+      label: "Token",
+      type: "password",
+      required: true,
+      helpText: "The Bearer token to include in the Authorization header.",
+    },
+  },
+  async createSession(args): Promise<CredentialSession> {
+    const token = String(args.material.token ?? "");
+    if (!token) {
+      throw new Error("Bearer token credential material is incomplete: token is required.");
+    }
+    return {
+      applyToRequest: (_spec): HttpCredentialDelta => ({
+        headers: { authorization: `Bearer ${token}` },
+      }),
+    };
+  },
+  async test(args) {
+    const token = String(args.material.token ?? "");
+    return {
+      status: token.length > 0 ? "healthy" : "failing",
+      message: token.length > 0 ? "Bearer token is configured." : "Token is missing.",
+      testedAt: new Date().toISOString(),
+    };
+  },
+});

package/src/credentials/OAuth2ClientCredentialsTypeFactory.ts

@@ -0,0 +1,117 @@
+import { defineCredential } from "@codemation/core";
+import type { CredentialSession, HttpCredentialDelta } from "../http/httpRequest.types";
+import { OAuth2TokenExchangeFactory } from "./OAuth2TokenExchangeFactory";
+
+/**
+ * OAuth2 client-credentials flow credential.
+ *
+ * This is a machine-to-machine flow: no user redirect occurs. The session
+ * POSTs to the configured `tokenUrl` with `client_credentials` grant, caches
+ * the resulting access token for the duration of the session, and injects it
+ * as `Authorization: Bearer <token>` on each request.
+ *
+ * Token caching is per-session only (one createSession call = one token fetch
+ * at most). Cross-session caching would require host-level state and is out of
+ * scope here. Because the engine creates a fresh session per execution, a new
+ * token is fetched once per node activation.
+ *
+ * NOTE: `auth` is intentionally omitted from the definition. The OAuth2
+ * `auth: { kind: "oauth2" }` shape signals an authorization-code / user-redirect
+ * flow; using it here would cause the host UI to render an OAuth consent button
+ * that goes nowhere. Client-credentials is a purely server-side flow.
+ */
+export const oauth2ClientCredentialsType = defineCredential({
+  key: "core-nodes.oauth2-client-credentials",
+  label: "OAuth2 Client Credentials",
+  description:
+    "Machine-to-machine OAuth2 using the client_credentials grant. Exchanges client ID and secret for a bearer token before each workflow execution.",
+  public: {
+    tokenUrl: {
+      label: "Token URL",
+      type: "string",
+      required: true,
+      helpText: "The token endpoint URL, e.g. https://auth.example.com/oauth/token.",
+    },
+    scopes: {
+      label: "Scopes",
+      type: "string",
+      helpText: "Space-separated list of OAuth2 scopes to request (optional).",
+    },
+    audience: {
+      label: "Audience",
+      type: "string",
+      helpText: "Optional audience parameter sent to the token endpoint.",
+      visibility: "advanced",
+    },
+  },
+  secret: {
+    clientId: {
+      label: "Client ID",
+      type: "string",
+      required: true,
+    },
+    clientSecret: {
+      label: "Client Secret",
+      type: "password",
+      required: true,
+    },
+  },
+  async createSession(args): Promise<CredentialSession> {
+    const tokenUrl = String(args.publicConfig.tokenUrl ?? "");
+    const clientId = String(args.material.clientId ?? "");
+    const clientSecret = String(args.material.clientSecret ?? "");
+
+    if (!tokenUrl || !clientId || !clientSecret) {
+      throw new Error("OAuth2 client credentials are incomplete: tokenUrl, clientId, and clientSecret are required.");
+    }
+
+    // Fetch the token eagerly so any failure surfaces at session creation time.
+    const accessToken = await new OAuth2TokenExchangeFactory().create({
+      tokenUrl,
+      clientId,
+      clientSecret,
+      scopes: String(args.publicConfig.scopes ?? ""),
+      audience: String(args.publicConfig.audience ?? ""),
+    });
+
+    return {
+      applyToRequest: (_spec): HttpCredentialDelta => ({
+        headers: { authorization: `Bearer ${accessToken}` },
+      }),
+    };
+  },
+  async test(args) {
+    const tokenUrl = String(args.publicConfig.tokenUrl ?? "");
+    const clientId = String(args.material.clientId ?? "");
+    const clientSecret = String(args.material.clientSecret ?? "");
+
+    if (!tokenUrl || !clientId || !clientSecret) {
+      return {
+        status: "failing",
+        message: "tokenUrl, clientId, and clientSecret are all required.",
+        testedAt: new Date().toISOString(),
+      };
+    }
+
+    try {
+      await new OAuth2TokenExchangeFactory().create({
+        tokenUrl,
+        clientId,
+        clientSecret,
+        scopes: String(args.publicConfig.scopes ?? ""),
+        audience: String(args.publicConfig.audience ?? ""),
+      });
+      return {
+        status: "healthy",
+        message: "Token exchange succeeded.",
+        testedAt: new Date().toISOString(),
+      };
+    } catch (error) {
+      return {
+        status: "failing",
+        message: error instanceof Error ? error.message : String(error),
+        testedAt: new Date().toISOString(),
+      };
+    }
+  },
+});