@ingram-cloud/pulumi 1.0.0 → 1.1.0

package/README.md

@@ -88,6 +88,35 @@ const curator = new ic.IcAgent("curator", {
 export const curatorAgentId = curator.agentId;
 ```
 
+**MCP Apps UI templates.** Pass `uiTemplates` to attach interactive HTML bundles
+(MCP Apps, SEP-1865). Each template's bytes upload when they (or the metadata)
+change, and its name + content hash + `tool`/`csp`/`permissions` fold into the
+content signature — so a template edit publishes and rolls out a new version like
+an instruction change. Provide the HTML as an absolute `htmlPath` or inline
+`html`; a `tool` binds it as a typed app-tool. Dropping a template from the array
+deletes it from the draft.
+
+```ts
+import { join } from "node:path";
+
+const bookkeeper = new ic.IcAgent("bookkeeper", {
+  ...conn,
+  instructions: BOOKKEEPER_INSTRUCTIONS,
+  uiTemplates: [
+    {
+      name: "cash_chart",
+      htmlPath: join(__dirname, "ui/cash-chart.html"),
+      tool: {
+        description: "Show an interactive cash-flow chart.",
+        input_schema: { type: "object", properties: {}, required: [] },
+        instruction: "Call get_cash_flow_history, then render_app with template cash_chart.",
+        mutating: false,
+      },
+    },
+  ],
+});
+```
+
 > Attaching **existing** smiths to a agent is a one-time fleet backfill —
 > keep it as the app's migration script. New smiths attach at birth in app code.
 > Pulumi does not own per-smith runtime state.

package/dist/resources.d.ts

@@ -37,6 +37,38 @@ export interface AgentVariable {
     description?: string | null;
     required?: boolean;
 }
+/** CSP domain allowlists for the sandboxed iframe (the `_meta.ui.csp` shape). */
+export interface UiCsp {
+    connectDomains?: string[];
+    resourceDomains?: string[];
+    frameDomains?: string[];
+    baseUriDomains?: string[];
+}
+/** A typed app-tool bound to a template (Rung 2): the host's model calls it and
+ *  the template renders the result. */
+export interface UiResourceTool {
+    description: string;
+    /** JSON Schema for the tool's arguments. */
+    input_schema?: Record<string, unknown>;
+    /** Scoped instruction the smith runs with when this tool is called. */
+    instruction?: string | null;
+    /** Writes gate through approval; reads flow freely. */
+    mutating?: boolean;
+}
+/** One UI template declared on an `IcAgent`. Provide the HTML via `htmlPath`
+ *  (read at `pulumi up`, so use an absolute path) or inline `html`. */
+export interface UiTemplate {
+    /** Template name (`[a-z0-9][a-z0-9_-]*`, ≤63) — the `ui://…/{name}` handle. */
+    name: string;
+    /** Absolute path to the HTML bundle. One of `htmlPath` / `html` is required. */
+    htmlPath?: string;
+    /** Inline HTML, as an alternative to `htmlPath`. */
+    html?: string;
+    csp?: UiCsp;
+    /** Permissions-Policy-style host permissions the template requests. */
+    permissions?: Record<string, unknown>;
+    tool?: UiResourceTool;
+}
 export interface IcAgentArgs {
     baseUrl: pulumi.Input<string>;
     token: pulumi.Input<string>;
@@ -57,6 +89,14 @@ export interface IcAgentArgs {
     /** Opt into observational-memory consolidation (background, billed). Default off. */
     memoryConsolidation?: pulumi.Input<boolean>;
     variables?: pulumi.Input<AgentVariable[]>;
+    /**
+     * MCP Apps UI templates attached to the agent. Each template's HTML bundle is
+     * uploaded when its bytes or metadata change, and its name + content hash +
+     * metadata fold into the content signature — so a template edit publishes and
+     * rolls out a new version like an instruction change. Provide the HTML via an
+     * absolute `htmlPath` or inline `html`.
+     */
+    uiTemplates?: pulumi.Input<UiTemplate[]>;
     /** Release note recorded when a new version is published. */
     publishNote?: pulumi.Input<string>;
     /** Rollout percentage for the published version (default 100). */

package/dist/resources.js

@@ -145,6 +145,80 @@ function makePutResource(cfg) {
         },
     };
 }
+// Read each template's HTML bundle (from `htmlPath` or inline `html`), hash the
+// bytes with the same sha256-hex the API stores as `content_hash`, and carry the
+// metadata through. Module-scope + node built-ins required inside so Pulumi's
+// closure serialization captures it (the providers otherwise assume only global
+// `fetch`).
+function resolveUiTemplates(templates) {
+    if (!templates?.length)
+        return [];
+    const { createHash } = require("node:crypto");
+    return templates.map((t) => {
+        let bytes;
+        if (t.html !== undefined)
+            bytes = Buffer.from(t.html, "utf8");
+        else if (t.htmlPath)
+            bytes = require("node:fs").readFileSync(t.htmlPath);
+        else
+            throw new Error(`uiTemplate "${t.name}": set htmlPath or html`);
+        return {
+            name: t.name,
+            bytes,
+            contentHash: createHash("sha256").update(bytes).digest("hex"),
+            csp: t.csp,
+            permissions: t.permissions,
+            tool: t.tool,
+        };
+    });
+}
+// Multipart upload of one template to POST /v1/agents/{aid}/ui — the HTML `file`
+// part plus a JSON `metadata` part. Not `icRequest` (that JSON-encodes the body);
+// uses global FormData/File (Node ≥18).
+async function uploadUiTemplate(baseUrl, token, aid, t) {
+    const form = new FormData();
+    form.set("file", new File([new Uint8Array(t.bytes)], `${t.name}.html`, { type: "text/html" }));
+    const meta = { name: t.name };
+    if (t.csp)
+        meta.csp = t.csp;
+    if (t.permissions)
+        meta.permissions = t.permissions;
+    if (t.tool)
+        meta.tool = t.tool;
+    form.set("metadata", JSON.stringify(meta));
+    const res = await fetch(`${baseUrl}/v1/agents/${aid}/ui`, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${token}`, "IC-Api-Version": exports.IC_API_VERSION },
+        body: form,
+    });
+    if (!res.ok) {
+        const err = new Error(`IC POST /v1/agents/${aid}/ui → ${res.status}: ${(await res.text()).slice(0, 400)}`);
+        err.status = res.status;
+        throw err;
+    }
+}
+// Reconcile the agent's UI templates against its draft `current` state: upload any
+// whose bytes or metadata drifted (or are new), delete any the resource no longer
+// declares. The draft this leaves behind is what the publish step snapshots.
+async function syncUiTemplates(i, id, current) {
+    const desired = resolveUiTemplates(i.uiTemplates);
+    const eq = (a, b) => JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+    for (const t of desired) {
+        const cur = current.find((e) => e?.name === t.name);
+        const unchanged = cur &&
+            cur.content_hash === t.contentHash &&
+            eq(cur.tool, t.tool) &&
+            eq(cur.csp, t.csp) &&
+            eq(cur.permissions, t.permissions);
+        if (!unchanged)
+            await uploadUiTemplate(i.baseUrl, i.token, id, t);
+    }
+    for (const e of current) {
+        const name = e?.name;
+        if (typeof name === "string" && !desired.some((t) => t.name === name))
+            await icRequest(i.baseUrl, i.token, "DELETE", `/v1/agents/${id}/ui/${encodeURIComponent(name)}`);
+    }
+}
 // Lower-case, hyphenate, trim — matches the API's slug derivation so a
 // logical-name-derived slug lines up with what the server would compute.
 function slugify(s) {
@@ -169,17 +243,40 @@ function agentBody(i) {
         variables: i.variables ?? [],
     };
 }
+// Canonical, name-sorted signature of an agent's frozen UI templates: each
+// entry's name + content hash + tool/csp/permissions metadata. Both the resource
+// inputs (hash computed from local bytes) and a published version's snapshot
+// (hash already stored) map onto this shape, so a template edit moves the
+// signature exactly one way.
+function uiResourcesSig(list) {
+    return (list ?? [])
+        .map((e) => ({
+        name: e.name,
+        content_hash: e.content_hash,
+        tool: e.tool ?? null,
+        csp: e.csp ?? null,
+        permissions: e.permissions ?? null,
+    }))
+        .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+}
 // Stable signature of the *content* that warrants a new published version
 // (name and rollout% deliberately excluded — a rename/restage is not new content).
 function agentContentSig(s) {
-    return JSON.stringify({
+    const base = {
         instructions: s.instructions ?? null,
         model: s.model ?? null,
         tools: [...(s.enabled_hosted_tools ?? [])].sort(),
         auto_memory: s.auto_memory ?? null,
         memory_consolidation: s.memory_consolidation ?? null,
         variables: s.variables ?? [],
-    });
+    };
+    // Only add the key when templates exist, so agents without any keep a
+    // byte-identical signature to pre-uiTemplates releases (no spurious republish
+    // on the first `up` after upgrading the library).
+    const ui = uiResourcesSig(s.ui_resources);
+    if (ui.length)
+        base.ui_resources = ui;
+    return JSON.stringify(base);
 }
 // Map the camelCase resource inputs onto the canonical snapshot shape.
 function inputsToSnapshot(i) {
@@ -190,6 +287,15 @@ function inputsToSnapshot(i) {
         auto_memory: i.autoMemory,
         memory_consolidation: i.memoryConsolidation,
         variables: i.variables,
+        // Resolve each template's bytes and hash so a HTML edit shows up in the
+        // signature (the API's `content_hash` uses the same sha256-hex).
+        ui_resources: resolveUiTemplates(i.uiTemplates).map((t) => ({
+            name: t.name,
+            content_hash: t.contentHash,
+            tool: t.tool,
+            csp: t.csp,
+            permissions: t.permissions,
+        })),
     };
 }
 async function findAgentBySlug(baseUrl, token, slug) {
@@ -234,6 +340,9 @@ async function reconcileAgent(i, knownId, priorSig) {
         await icRequest(i.baseUrl, i.token, "PATCH", `/v1/agents/${id}`, agentBody(i));
     }
     const bp = await icRequest(i.baseUrl, i.token, "GET", `/v1/agents/${id}`);
+    // Reconcile UI templates against the draft before publishing so a template
+    // change rides the same publish + rollout as an instruction change.
+    await syncUiTemplates(i, id, (bp.draft?.ui_resources ?? []));
     const desiredSig = agentContentSig(inputsToSnapshot(i));
     // On the create path we don't know the prior sig — compare to what's actually
     // published so adopting a script-made agent doesn't churn a needless version.
@@ -295,8 +404,13 @@ const agentProvider = {
         // update (the old and new slugs differ, so create-before-delete is safe).
         if (olds.slug !== news.slug)
             return { changes: true, replaces: ["slug"] };
-        const contentChanged = agentContentSig(inputsToSnapshot(olds)) !==
-            agentContentSig(inputsToSnapshot(news));
+        // Compare the freshly-resolved desired signature to the one STORED at the
+        // last apply — not a re-resolve of `olds`. A file-backed template edits the
+        // same `htmlPath`, so re-reading `olds` would hash the new bytes and hide
+        // the change; the stored `contentSig` froze the prior hash.
+        const oldSig = olds.contentSig ??
+            agentContentSig(inputsToSnapshot(olds));
+        const contentChanged = oldSig !== agentContentSig(inputsToSnapshot(news));
         const nameChanged = (olds.name ?? olds.slug) !== (news.name ?? news.slug);
         const rolloutChanged = (olds.rolloutPercent ?? 100) !== (news.rolloutPercent ?? 100);
         return { changes: contentChanged || nameChanged || rolloutChanged };
@@ -333,6 +447,7 @@ class IcAgent extends pulumi.dynamic.Resource {
             autoMemory: undefined,
             memoryConsolidation: undefined,
             variables: undefined,
+            uiTemplates: undefined,
             publishNote: undefined,
             rolloutPercent: undefined,
             agentId: undefined,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ingram-cloud/pulumi",
-	"version": "1.0.0",
+	"version": "1.1.0",
 	"description": "Pulumi dynamic resources for the Ingram Cloud /v1 API — projects, project tokens, agents, MCP servers, channels, webhooks, model keys.",
 	"license": "MIT",
 	"homepage": "https://cloud.ingram.tech",