@ingram-cloud/pulumi 2.0.0 → 2.1.0

package/README.md

@@ -145,6 +145,35 @@ export const pageUrl = page.pageUrl; // https://cloud.ingram.tech/hosted/dep_…
 > change to any of those (or to `agentId`) **replaces** the page and mints a fresh
 > `pageUrl`. The agent's instructions change on the `IcAgent`, not here.
 
+### IcSkill (declare in the APP repo)
+
+An [Agent Skills](https://cloud.ingram.tech/docs/skills) bundle: a folder
+anchored by `SKILL.md`, uploaded whole and versioned server-side. Declared by
+**local directory** — the folder is the unit — like `IcAgent`'s `uiTemplates`
+and the vector-store-shaped file attachments elsewhere in this pattern. The
+bytes are read at `pulumi up`; any edit inside the folder publishes a new
+immutable version and moves `default_version` to it, because a version is
+immutable and nothing resolving by default would otherwise see the change.
+
+```ts
+// The folder is the unit. Its basename is the skill's name, and any edit
+// inside it publishes a new immutable version and moves the default.
+const vatFiling = new ic.IcSkill("vat-filing", {
+  ...conn,
+  path: join(__dirname, "skills/vat-filing"),
+});
+
+// Put it in front of a fleet. Order matters: a run that fills its search index
+// keeps the earlier entries and drops the rest.
+const biller = new ic.IcAgent("biller", {
+  ...conn,
+  instructions: AGENT_SPECS.biller.instructions,
+  skills: [{ skill_id: vatFiling.skillId }],
+  // A skill's scripts/ only run through the run_command hosted tool.
+  enabledHostedTools: ["run_command"],
+});
+```
+
 ### IcMcpServer, IcOauthProvider, IcTelegramBot, IcWhatsAppConfig, IcEmail, IcWebhook, IcModelKey (declare in INFRA)
 
 ```ts
@@ -154,6 +183,12 @@ new ic.IcMcpServer("thornhill-mcp", {
   authKind: "bearer", secret: mcpSecret,
 });
 
+// The tool list is discovered at create, not on every `pulumi up` — nothing in
+// this stack changes when your *server's* tools do, so `toolsDiscovered` is what
+// was true at registration. Ingram Cloud re-discovers on the run path once a
+// manifest is an hour old; call `POST /v1/tenant/mcp/{serverName}/refresh` at the
+// end of a deploy that changed your tools if an hour is too long to wait.
+
 // An `oauth`-kind server forwards each end-user's own stored token; its
 // provider record tells IC how tokens refresh. Webhook-delegation mode (a
 // refreshWebhook and NO clientSecret): IC POSTs { connection_id } to the

package/dist/resources.d.ts

@@ -37,6 +37,13 @@ export interface AgentVariable {
     description?: string | null;
     required?: boolean;
 }
+/** One skill reference in an agent's `skills` array. Omitted `version` follows
+ *  the skill's `default_version` and is frozen at publish. Pair with
+ *  {@link IcSkill}'s `skillId` output. */
+export interface AgentSkillRef {
+    skillId: string;
+    version?: number;
+}
 /** CSP domain allowlists for the sandboxed iframe (the `_meta.ui.csp` shape). */
 export interface UiCsp {
     connectDomains?: string[];
@@ -97,6 +104,15 @@ export interface IcAgentArgs {
     /** Opt into observational-memory consolidation (background, billed). Default off. */
     memoryConsolidation?: pulumi.Input<boolean>;
     variables?: pulumi.Input<AgentVariable[]>;
+    /**
+     * Skills (`skl_…`) attached to the agent, in order. Order is not cosmetic: a
+     * run whose skills together exceed the search-index ceiling keeps them in
+     * this order and drops the rest, so it is the survival priority. Folds into
+     * the content signature unsorted, unlike `enabledHostedTools`/`vectorStoreIds`
+     * — reordering is itself a content change. Pair with {@link IcSkill}'s
+     * `skillId` output.
+     */
+    skills?: pulumi.Input<AgentSkillRef[]>;
     /**
      * 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 +
@@ -117,6 +133,23 @@ export declare class IcAgent extends pulumi.dynamic.Resource {
     readonly activeVersion: pulumi.Output<number>;
     constructor(name: string, args: IcAgentArgs, opts?: pulumi.CustomResourceOptions);
 }
+export interface IcSkillArgs {
+    baseUrl: pulumi.Input<string>;
+    token: pulumi.Input<string>;
+    /**
+     * Absolute path to the skill's directory — the folder anchored by `SKILL.md`,
+     * whose basename is the skill's name. Read at `pulumi up`; edit any file in it
+     * and a new immutable version is published and made the default.
+     */
+    path: pulumi.Input<string>;
+}
+export declare class IcSkill extends pulumi.dynamic.Resource {
+    /** The `skl_…` id (same as `.id`, exposed for convenience). */
+    readonly skillId: pulumi.Output<string>;
+    /** The version this stack last published, and the current `default_version`. */
+    readonly version: pulumi.Output<number>;
+    constructor(name: string, args: IcSkillArgs, opts?: pulumi.CustomResourceOptions);
+}
 /** One source file on an {@link IcVectorStore}, provided by local path. */
 export interface VectorStoreFile {
     /** Absolute path to the file to ingest (read at `pulumi up`, like `htmlPath`). */

package/dist/resources.js

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.IcWebPage = exports.IcProjectToken = exports.IcProject = exports.IcModelKey = exports.IcWebhook = exports.IcEmail = exports.IcWhatsAppConfig = exports.IcOauthProvider = exports.IcTelegramBot = exports.IcMcpServer = exports.IcVectorStore = exports.IcAgent = exports.IC_API_VERSION = void 0;
+exports.IcWebPage = exports.IcProjectToken = exports.IcProject = exports.IcModelKey = exports.IcWebhook = exports.IcEmail = exports.IcWhatsAppConfig = exports.IcOauthProvider = exports.IcTelegramBot = exports.IcMcpServer = exports.IcVectorStore = exports.IcSkill = exports.IcAgent = exports.IC_API_VERSION = void 0;
 /**
  * Ingram Cloud /v1 tenant configuration as Pulumi dynamic resources.
  *
@@ -248,6 +248,10 @@ function agentBody(i) {
         auto_memory: i.autoMemory ?? null,
         memory_consolidation: i.memoryConsolidation ?? null,
         variables: i.variables ?? [],
+        skills: (i.skills ?? []).map((s) => ({
+            skill_id: s.skillId,
+            ...(s.version != null ? { version: s.version } : {}),
+        })),
     };
 }
 // Canonical, name-sorted signature of an agent's frozen UI templates: each
@@ -291,6 +295,12 @@ function agentContentSig(s) {
     const vs = [...(s.vector_store_ids ?? [])].sort();
     if (vs.length)
         base.vector_store_ids = vs;
+    // Skills, deliberately NOT sorted: reference order is the run's index-ceiling
+    // drop priority, so reordering the array is itself a content change worth a
+    // new version, not a no-op like reordering hosted tools or vector stores is.
+    const skills = s.skills ?? [];
+    if (skills.length)
+        base.skills = skills;
     return JSON.stringify(base);
 }
 // Map the camelCase resource inputs onto the canonical snapshot shape.
@@ -304,6 +314,10 @@ function inputsToSnapshot(i) {
         auto_memory: i.autoMemory,
         memory_consolidation: i.memoryConsolidation,
         variables: i.variables,
+        skills: (i.skills ?? []).map((s) => ({
+            skill_id: s.skillId,
+            ...(s.version != null ? { version: s.version } : {}),
+        })),
         // 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) => ({
@@ -451,6 +465,10 @@ const agentProvider = {
                     autoMemory: d.auto_memory ?? undefined,
                     memoryConsolidation: d.memory_consolidation ?? undefined,
                     variables: d.variables ?? [],
+                    skills: (d.skills ?? []).map((s) => ({
+                        skillId: s.skill_id,
+                        version: s.version,
+                    })),
                 },
             };
         });
@@ -467,6 +485,7 @@ class IcAgent extends pulumi.dynamic.Resource {
             autoMemory: undefined,
             memoryConsolidation: undefined,
             variables: undefined,
+            skills: undefined,
             uiTemplates: undefined,
             publishNote: undefined,
             rolloutPercent: undefined,
@@ -481,6 +500,128 @@ class IcAgent extends pulumi.dynamic.Resource {
     }
 }
 exports.IcAgent = IcAgent;
+/** Walk a skill directory into the parts the upload sends.
+ *
+ *  `require` inline rather than a top-level import: Pulumi serializes a dynamic
+ *  provider's closure, and this is the idiom the vector-store resource next door
+ *  already uses to read local files. */
+function resolveSkillFiles(dir) {
+    if (!dir)
+        throw new Error("skill: `path` is required");
+    const fs = require("node:fs");
+    const nodePath = require("node:path");
+    const root = nodePath.basename(nodePath.resolve(dir));
+    const out = [];
+    const walk = (at, prefix) => {
+        for (const entry of fs.readdirSync(at, { withFileTypes: true })) {
+            const full = nodePath.join(at, entry.name);
+            const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+            if (entry.isDirectory())
+                walk(full, rel);
+            else if (entry.isFile())
+                out.push({ rel: `${root}/${rel}`, bytes: fs.readFileSync(full) });
+        }
+    };
+    walk(nodePath.resolve(dir), "");
+    if (!out.some((f) => f.rel === `${root}/SKILL.md`))
+        throw new Error(`skill: ${dir} has no SKILL.md`);
+    return out.sort((a, b) => (a.rel < b.rel ? -1 : a.rel > b.rel ? 1 : 0));
+}
+/** A content signature over the whole bundle — what `diff` compares. */
+function skillSig(dir) {
+    if (!dir)
+        return "";
+    const { createHash } = require("node:crypto");
+    const hash = createHash("sha256");
+    for (const file of resolveSkillFiles(dir)) {
+        hash.update(file.rel);
+        hash.update(file.bytes);
+    }
+    return hash.digest("hex");
+}
+/** Upload a bundle as repeated `files[]` parts. Not `icRequest` (that
+ *  JSON-encodes); uses global FormData/File (Node ≥18), like `uploadFile`. */
+async function uploadSkillBundle(baseUrl, token, path, dir) {
+    const form = new FormData();
+    for (const file of resolveSkillFiles(dir))
+        form.append("files[]", new File([file.bytes], file.rel));
+    const res = await fetch(`${baseUrl}${path}`, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${token}`,
+            "IC-Api-Version": exports.IC_API_VERSION,
+        },
+        body: form,
+    });
+    const text = await res.text();
+    if (!res.ok) {
+        const err = new Error(`IC POST ${path} → ${res.status}: ${text.slice(0, 400)}`);
+        err.status = res.status;
+        throw err;
+    }
+    return text ? JSON.parse(text) : {};
+}
+const skillProvider = {
+    async create(i) {
+        const skill = await uploadSkillBundle(i.baseUrl, i.token, "/v1/skills", i.path);
+        return {
+            id: skill.id,
+            outs: {
+                ...i,
+                skillId: skill.id,
+                version: skill.default_version,
+                contentSig: skillSig(i.path),
+            },
+        };
+    },
+    async update(id, _olds, news) {
+        // A version is immutable, so an edited bundle is a new one — and the
+        // default has to move, or nothing that resolves by default would see it.
+        const published = await uploadSkillBundle(news.baseUrl, news.token, `/v1/skills/${id}/versions`, news.path);
+        await icRequest(news.baseUrl, news.token, "POST", `/v1/skills/${id}`, {
+            default_version: published.version,
+        });
+        return {
+            outs: {
+                ...news,
+                skillId: id,
+                version: published.version,
+                contentSig: skillSig(news.path),
+            },
+        };
+    },
+    async delete(id, props) {
+        await icRequest(props.baseUrl, props.token, "DELETE", `/v1/skills/${id}`);
+    },
+    async diff(_id, olds, news) {
+        // Compare against the sig STORED at the last apply, not a re-resolve of
+        // olds: olds.path points at the same folder, whose bytes have already
+        // changed, so re-reading it would hide the change (same reasoning as the
+        // agent and vector-store diffs).
+        const changed = (olds.contentSig ?? "") !== skillSig(news.path);
+        return { changes: changed };
+    },
+    async read(id, props) {
+        return read404(() => icRequest(props.baseUrl, props.token, "GET", `/v1/skills/${id}`), (skill) => {
+            if (!skill || !skill.id)
+                return { id: "" };
+            return {
+                id,
+                props: {
+                    ...props,
+                    skillId: skill.id,
+                    version: skill.default_version,
+                },
+            };
+        });
+    },
+};
+class IcSkill extends pulumi.dynamic.Resource {
+    constructor(name, args, opts) {
+        super(skillProvider, name, { skillId: undefined, version: undefined, contentSig: undefined, ...args }, { ...opts, additionalSecretOutputs: ["token"] });
+    }
+}
+exports.IcSkill = IcSkill;
 // Read each declared file's bytes and hash them (same sha256-hex the API keys
 // files by) so an edit shows up in the file signature. Module-scope + node
 // built-ins required inside for Pulumi's closure serialization.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ingram-cloud/pulumi",
-	"version": "2.0.0",
+	"version": "2.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",
@@ -29,10 +29,10 @@
 	},
 	"devDependencies": {
 		"@ingram-tech/oxlint-config": "^0.2.2",
-		"@pulumi/pulumi": "^3.253.0",
-		"@types/node": "^26.1.1",
-		"oxfmt": "^0.59.0",
-		"oxlint": "^1.74.0",
+		"@pulumi/pulumi": "^3.255.0",
+		"@types/node": "^26.1.2",
+		"oxfmt": "0.62.0",
+		"oxlint": "^1.77.0",
 		"typescript": "^7.0.2"
 	}
 }