Skip to content

The Open Standard for Generative UI

Add artifactTool on @openuidev/lang-core/cloud (#1146)

AB923deba4d96f
diff --git a/docs/app/api/openui-cloud/chat/route.ts b/docs/app/api/openui-cloud/chat/route.ts
index 4dfe8f064..d4519e9ee 100644
--- a/docs/app/api/openui-cloud/chat/route.ts
+++ b/docs/app/api/openui-cloud/chat/route.ts
@@ -3,7 +3,7 @@ import { unavailableResponse } from "@/lib/openui-cloud/errors";
import { resolveRequestedModel } from "@/lib/openui-cloud/models";
import { hasAllowedOrigin, hasJsonContentType, readLimitedJson } from "@/lib/openui-cloud/request";
import { generateSystemPrompt } from "@openuidev/lang-core";
-import { artifactTool } from "@openuidev/thesys-server";
+import { artifactTool } from "@openuidev/lang-core/cloud";
import OpenAI from "openai";
import type { ResponseInputItem } from "openai/resources/responses/responses";
diff --git a/docs/package.json b/docs/package.json
index f42c2d6cf..b31650421 100644
--- a/docs/package.json
+++ b/docs/package.json
@@ -24,7 +24,6 @@
"@openuidev/react-lang": "workspace:^",
"@openuidev/react-ui": "workspace:^",
"@openuidev/thesys": "0.3.2",
- "@openuidev/thesys-server": "0.1.4",
"@phosphor-icons/react": "^2.1.10",
"@radix-ui/react-dialog": "1.1.15",
"@radix-ui/react-tooltip": "1.2.7",
diff --git a/packages/lang-core/README.md b/packages/lang-core/README.md
index cbf42ced0..2755f25fe 100644
--- a/packages/lang-core/README.md
+++ b/packages/lang-core/README.md
@@ -96,6 +96,17 @@ const myLibraryPrompt = generateSystemPrompt({
});
```
+Enable managed slides and reports with `artifactTool` from the Cloud subpath:
+
+```ts
+import { artifactTool } from "@openuidev/lang-core/cloud";
+
+const tools = [
+ artifactTool({ artifacts: ["slides", "report"] }),
+ { type: "web_search" },
+];
+```
+
### Merge incremental edits
```ts
@@ -128,6 +139,12 @@ const merged = mergeStatements(original, patch);
**`ToolSpec`** describes a tool for prompt generation (name, description, inputSchema, outputSchema). Shape inspired by MCP's tool schema.
+### OpenUI Cloud
+
+| Export | Description |
+| :--- | :--- |
+| `artifactTool(options?)` | From `@openuidev/lang-core/cloud`. Responses `tools[]` entry for Cloud's managed slides/report artifacts. |
+
## Telemetry
Lang Core sends pseudonymous installation telemetry during `postinstall`.
diff --git a/packages/lang-core/package.json b/packages/lang-core/package.json
index 21cd5a8df..3427c9204 100644
--- a/packages/lang-core/package.json
+++ b/packages/lang-core/package.json
@@ -1,12 +1,19 @@
{
"name": "@openuidev/lang-core",
- "version": "0.2.17",
+ "version": "0.2.18",
"description": "Framework-agnostic core for OpenUI Lang: parser, prompt generation, validation, and type definitions",
"license": "MIT",
"type": "module",
"main": "dist/index.cjs",
"module": "dist/index.mjs",
"types": "dist/index.d.cts",
+ "typesVersions": {
+ "*": {
+ "cloud": [
+ "dist/cloud.d.cts"
+ ]
+ }
+ },
"sideEffects": false,
"files": [
"dist",
@@ -23,6 +30,16 @@
"types": "./dist/index.d.cts",
"default": "./dist/index.cjs"
}
+ },
+ "./cloud": {
+ "import": {
+ "types": "./dist/cloud.d.mts",
+ "default": "./dist/cloud.mjs"
+ },
+ "require": {
+ "types": "./dist/cloud.d.cts",
+ "default": "./dist/cloud.cjs"
+ }
}
},
"scripts": {
diff --git a/packages/lang-core/src/__tests__/cloud.test.ts b/packages/lang-core/src/__tests__/cloud.test.ts
new file mode 100644
index 000000000..34e7fb3b7
--- /dev/null
+++ b/packages/lang-core/src/__tests__/cloud.test.ts
@@ -0,0 +1,77 @@
+import { describe, expect, it } from "vitest";
+import { artifactTool, REPORT_LIBRARY_VERSION, SLIDES_LIBRARY_VERSION } from "../cloud";
+
+const CLOUD_SUPPORTED_ARTIFACT_TYPES = ["slides", "report"];
+
+describe("artifactTool — defaults", () => {
+ const ALL_WITH_VERSION = {
+ type: "artifact",
+ artifacts: [
+ { artifact_type: "slides", library_version: SLIDES_LIBRARY_VERSION },
+ { artifact_type: "report", library_version: REPORT_LIBRARY_VERSION },
+ ],
+ };
+
+ it("no options → all types WITH library_version", () => {
+ expect(artifactTool()).toEqual(ALL_WITH_VERSION);
+ });
+
+ it("empty options → all types WITH library_version too", () => {
+ expect(artifactTool({})).toEqual(ALL_WITH_VERSION);
+ });
+});
+
+describe("artifactTool — restriction", () => {
+ it("'slides' shorthand → entry with pinned version", () => {
+ expect(artifactTool({ artifacts: ["slides"] })).toEqual({
+ type: "artifact",
+ artifacts: [{ artifact_type: "slides", library_version: SLIDES_LIBRARY_VERSION }],
+ });
+ });
+
+ it("'report' shorthand → entry with pinned version", () => {
+ expect(artifactTool({ artifacts: ["report"] })).toEqual({
+ type: "artifact",
+ artifacts: [{ artifact_type: "report", library_version: REPORT_LIBRARY_VERSION }],
+ });
+ });
+
+ it("mixed shorthand + object entries, order preserved", () => {
+ const entry = artifactTool({
+ artifacts: [{ type: "slides", instruction: "Use the corporate template." }, "report"],
+ });
+ expect(entry.artifacts?.map((a) => a.artifact_type)).toEqual(["slides", "report"]);
+ expect(entry.artifacts?.[0]?.instruction).toBe("Use the corporate template.");
+ expect(entry.artifacts?.[1]).not.toHaveProperty("instruction");
+ });
+
+ it("every emitted artifact_type is Cloud-supported", () => {
+ const entry = artifactTool({ artifacts: ["slides", "report"] });
+ for (const a of entry.artifacts ?? []) {
+ expect(CLOUD_SUPPORTED_ARTIFACT_TYPES).toContain(a.artifact_type);
+ }
+ });
+
+ it("libraryVersion override wins over the pinned constant", () => {
+ const entry = artifactTool({
+ artifacts: [{ type: "report", libraryVersion: "2.3.0" }],
+ });
+ expect(entry.artifacts?.[0]?.library_version).toBe("2.3.0");
+ });
+});
+
+describe("artifactTool — validation", () => {
+ it("empty artifacts array throws (omit to enable all)", () => {
+ expect(() => artifactTool({ artifacts: [] })).toThrow(/must not be empty/);
+ });
+
+ it("duplicate artifact kinds throw", () => {
+ expect(() => artifactTool({ artifacts: ["report", { type: "report" }] })).toThrow(/duplicate/);
+ });
+
+ it("unknown artifact kind throws — incl. 'presentation' (not wire vocabulary)", () => {
+ expect(() => artifactTool({ artifacts: ["presentation" as never] })).toThrow(
+ /unknown artifact type 'presentation'/,
+ );
+ });
+});
diff --git a/packages/lang-core/src/cloud.ts b/packages/lang-core/src/cloud.ts
new file mode 100644
index 000000000..ff03efba5
--- /dev/null
+++ b/packages/lang-core/src/cloud.ts
@@ -0,0 +1,95 @@
+export type ArtifactKind = "slides" | "report";
+
+export interface ArtifactOption {
+ type: ArtifactKind;
+ /** Per-artifact instruction, folded into the Cloud tool description. */
+ instruction?: string;
+ /** Override this package's pinned library version for this artifact. */
+ libraryVersion?: string;
+}
+
+export interface ArtifactToolOptions {
+ /** Which artifacts to enable. Omit to enable all artifact types. */
+ artifacts?: Array<ArtifactKind | ArtifactOption>;
+}
+
+export interface ArtifactWireEntry {
+ artifact_type: ArtifactKind;
+ instruction?: string;
+ library_version?: string;
+}
+
+/** The Responses `tools[]` entry enabling OpenUI Cloud's managed artifact tool. */
+export interface ResponsesArtifactToolEntry {
+ type: "artifact";
+ /** Absent → all supported artifact types enabled. */
+ artifacts?: ArtifactWireEntry[];
+}
+
+/**
+ * Wire pins for OpenUI Cloud's managed artifact libraries. Cloud rejects a
+ * non-numeric or too-old version.
+ */
+export const SLIDES_LIBRARY_VERSION = "0.1.0";
+export const REPORT_LIBRARY_VERSION = "0.1.0";
+
+const DEFAULT_LIBRARY_VERSION: Record<ArtifactKind, string> = {
+ slides: SLIDES_LIBRARY_VERSION,
+ report: REPORT_LIBRARY_VERSION,
+};
+
+/**
+ * Build the Responses `tools[]` entry that enables Cloud's managed artifact tool.
+ *
+ * tools: [artifactTool()] // all artifact types
+ * tools: [artifactTool({ artifacts: ["report"] })] // report only
+ * tools: [artifactTool({
+ * artifacts: [
+ * { type: "slides", instruction: "Use the corporate template." },
+ * "report",
+ * ],
+ * })]
+ *
+ * Pass at most one artifactTool() entry per request — Cloud keys the
+ * artifact config by tool type, so a second entry silently replaces the first.
+ */
+export function artifactTool(options: ArtifactToolOptions = {}): ResponsesArtifactToolEntry {
+ const { artifacts } = options;
+ if (artifacts === undefined) {
+ // Emit every supported type WITH its library_version so Cloud resolves to
+ // the OpenUI Lang format. A bare `{ type: "artifact" }` with no
+ // library_version is the legacy shape — not what a lang-core caller wants.
+ return {
+ type: "artifact",
+ artifacts: (Object.keys(DEFAULT_LIBRARY_VERSION) as ArtifactKind[]).map((kind) => ({
+ artifact_type: kind,
+ library_version: DEFAULT_LIBRARY_VERSION[kind],
+ })),
+ };
+ }
+ if (artifacts.length === 0) {
+ throw new Error(
+ "artifactTool: `artifacts` must not be empty — omit it to enable all artifact types.",
+ );
+ }
+
+ const seen = new Set<ArtifactKind>();
+ const entries: ArtifactWireEntry[] = artifacts.map((artifact) => {
+ const opt: ArtifactOption = typeof artifact === "string" ? { type: artifact } : artifact;
+ if (!(opt.type in DEFAULT_LIBRARY_VERSION)) {
+ throw new Error(
+ `artifactTool: unknown artifact type '${opt.type}'. Supported: ${Object.keys(DEFAULT_LIBRARY_VERSION).join(", ")}.`,
+ );
+ }
+ if (seen.has(opt.type)) {
+ throw new Error(`artifactTool: duplicate artifact '${opt.type}'.`);
+ }
+ seen.add(opt.type);
+ return {
+ artifact_type: opt.type,
+ ...(opt.instruction && { instruction: opt.instruction }),
+ library_version: opt.libraryVersion ?? DEFAULT_LIBRARY_VERSION[opt.type],
+ };
+ });
+ return { type: "artifact", artifacts: entries };
+}
diff --git a/packages/lang-core/tsdown.config.ts b/packages/lang-core/tsdown.config.ts
index b805735df..49bc42591 100644
--- a/packages/lang-core/tsdown.config.ts
+++ b/packages/lang-core/tsdown.config.ts
@@ -2,7 +2,7 @@ import { defineConfig } from "tsdown";
import packageJson from "./package.json" with { type: "json" };
export default defineConfig({
- entry: ["src/index.ts", "src/postinstall.ts"],
+ entry: ["src/index.ts", "src/postinstall.ts", "src/cloud.ts"],
format: ["esm", "cjs"],
dts: true,
sourcemap: true,
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 581f841e3..63518008f 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -84,9 +84,6 @@ importers:
'@openuidev/thesys':
specifier: 0.3.2
version: 0.3.2(@openuidev/lang-core@packages+lang-core)(@openuidev/react-headless@packages+react-headless)(@openuidev/react-lang@packages+react-lang)(@openuidev/react-ui@packages+react-ui)(@radix-ui/[email protected](@types/[email protected](@types/[email protected]))(@types/[email protected])([email protected]([email protected]))([email protected]))(@tiptap/[email protected](@tiptap/[email protected]))(@tiptap/[email protected])(@types/[email protected](@types/[email protected]))(@types/[email protected])([email protected]([email protected]))([email protected])([email protected])([email protected](@types/[email protected])([email protected]))
- '@openuidev/thesys-server':
- specifier: 0.1.4
- version: 0.1.4
'@phosphor-icons/react':
specifier: ^2.1.10
@@ -2188,9 +2185,6 @@ packages:
resolution: {integrity: sha512-eSYWTm620tTk45EKSedaUL8MFYI8hW164hIXsgIHyxu3VobUB3fFCu5t0hQby6OoWRPsG1KkKUG2M5UadiLiVg==}
engines: {node: '>=14'}
- '@openuidev/[email protected]':
- resolution: {integrity: sha512-kRP54tk5608IuTU0Rjwo4wE8oCpWIxLAphhBkNGHaeZd7hAXwLGmT/vcIZBIr8KQM3Riq/pczrOa/ksyXXtcvQ==}
-
'@openuidev/[email protected]':
resolution: {integrity: sha512-bVnVy2OcGawikt+R5QR4EBKtRvd0Y2PD9+Z94EClD5fSVtfi9VT9yztBp9a+r104SdB1GZuRuO3J/U+UALZgyg==}
engines: {node: '>=20'}
@@ -11639,8 +11633,6 @@ snapshots:
'@opentelemetry/[email protected]':
optional: true
- '@openuidev/[email protected]': {}
-
'@openuidev/[email protected](@openuidev/lang-core@packages+lang-core)(@openuidev/react-headless@packages+react-headless)(@openuidev/react-lang@packages+react-lang)(@openuidev/react-ui@packages+react-ui)(@radix-ui/[email protected](@types/[email protected](@types/[email protected]))(@types/[email protected])([email protected]([email protected]))([email protected]))(@tiptap/[email protected](@tiptap/[email protected]))(@tiptap/[email protected])(@types/[email protected](@types/[email protected]))(@types/[email protected])([email protected]([email protected]))([email protected])([email protected])([email protected](@types/[email protected])([email protected]))':
dependencies:
'@floating-ui/react-dom': 2.1.3([email protected]([email protected]))([email protected])