@kohala/devkit 0.1.7 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @kohala/devkit
 
+## 0.2.0
+
+- **TypeScript/JavaScript agents can now be shipped with the CLI.** `kohala
+  validate` and `kohala deploy` discover `.ts` / `.js` skill scripts
+  alongside `.py` (same extension table the platform uses) and report the
+  detected runtime per skill. A Node-lane skill's upload now carries
+  `runtimeLanguage` and the manifest's new `dependencies` (npm packages) as
+  `scriptDependencies`, so the platform runs its acceptance checks — compile,
+  security scan, npm allowlist — when the script is attached instead of
+  letting it fail on its first hosted run. A package outside the allowlist is
+  reported locally, with the platform's own message, before anything is sent
+  (`--allow-unknown-packages` defers to the server). A skill file with an
+  extension no runtime can execute is now a validation error for wrap-mode
+  agents. Python projects deploy byte-for-byte as before: their payload gains
+  no new fields.
+- **Start a TypeScript agent with one command.** `kohala init my-agent
+  --language ts` creates a typed `main.ts`, a local `_tools.ts` adapter with
+  the same API as the hosted Node SDK, strict TypeScript configuration, and
+  declared npm packages. The generated project validates, runs locally through
+  the Node lane, and produces a complete dry-run deploy plan without edits.
+
 ## 0.1.7
 
 - **BUG-006 fixed: `kohala deploy --run` no longer misreports every 409 as

package/CONTRIBUTING.md

@@ -24,6 +24,15 @@ npm test            # vitest (unit + CLI e2e)
 npm run build       # tsup -> dist/
 ```
 
+## Updating dependencies
+
+`devkit/package-lock.json` is committed so CI and local development install the
+same dependency tree. When changing dependencies, run `npm install` from the
+`devkit` directory and commit both `package.json` and `package-lock.json`.
+Use `npm ci` when you only need to install the committed dependency tree.
+CI pins npm 11.6.0 to avoid an npm 10 peer-resolution crash; use the same npm
+version when intentionally regenerating the lockfile.
+
 ## Ground rules
 
 - **Errors fail loudly.** No silent fallbacks, no mock LLM responses, no

package/README.md

@@ -54,6 +54,11 @@ skill scripts).
 }
 ```
 
+- Skill scripts can be Python (`main.py`) or TypeScript/JavaScript
+  (`main.ts`) — the extension picks the runtime, and a TypeScript agent
+  declares its npm packages with `"dependencies": ["zod"]` (allowlisted
+  packages only). `kohala run --local` executes Python skills; TypeScript
+  skills run hosted. See [MANIFEST.md](docs/MANIFEST.md#script-languages).
 - `runtimeMode: "wrap"` executes your script directly and validates its
   output (stdout). Use `llm.complete` from the script SDK to call an LLM
   mid-script (needs `ANTHROPIC_API_KEY` or `GEMINI_API_KEY`).

package/dist/cli/index.js

@@ -13,6 +13,45 @@ import pc from "picocolors";
 
 // src/manifest/schema.ts
 import { z } from "zod";
+
+// src/manifest/language.ts
+var RUNTIME_LANGUAGES = ["python", "node"];
+var ENTRYPOINT_EXTENSIONS = {
+  python: [".py"],
+  node: [".ts", ".mts", ".cts", ".js", ".mjs", ".cjs"]
+};
+var SCRIPT_FILE_EXTENSIONS = Object.values(ENTRYPOINT_EXTENSIONS).flat();
+var LANGUAGE_LABEL = {
+  python: "Python",
+  node: "TypeScript/JavaScript"
+};
+function languageForEntrypointFile(filename) {
+  const lower = (filename || "").toLowerCase();
+  for (const language of RUNTIME_LANGUAGES) {
+    if (ENTRYPOINT_EXTENSIONS[language].some((ext) => lower.endsWith(ext))) {
+      return language;
+    }
+  }
+  return null;
+}
+function skillLanguages(skills) {
+  return Object.entries(skills).map(([name, scriptFilename]) => ({
+    name,
+    scriptFilename,
+    language: languageForEntrypointFile(scriptFilename) ?? "python"
+  }));
+}
+function summarizeLanguages(skills) {
+  const languages = new Set(skillLanguages(skills).map((skill) => skill.language));
+  if (languages.size === 0) return "none";
+  if (languages.size > 1) return "mixed";
+  return [...languages][0];
+}
+function hasNodeSkill(skills) {
+  return skillLanguages(skills).some((skill) => skill.language === "node");
+}
+
+// src/manifest/schema.ts
 var BILLING_PERIODS = ["day", "week", "month"];
 var shapeValidatorSchema = z.object({
   type: z.literal("shape"),
@@ -53,6 +92,8 @@ var nameSchema = z.string().min(1).max(64).regex(
   /^[a-z0-9][a-z0-9_-]*$/i,
   "must start with a letter or digit and contain only letters, digits, '-' and '_'"
 );
+var skillScriptSchema = z.string().min(1);
+var dependenciesSchema = z.array(z.string().min(1).max(214)).max(50).default([]);
 var manifestSchema = z.object({
   name: nameSchema,
   /** The agent's mission text (platform: agentCharter). */
@@ -67,13 +108,43 @@ var manifestSchema = z.object({
    * "llm"   — run a real tool-use loop against the developer's own LLM key.
    */
   runtimeMode: z.enum(["wrap", "llm"]),
-  /** Map of skill name -> script filename, e.g. {"collect": "main.py"}. */
-  skills: z.record(z.string().min(1), z.string().min(1)).default({}),
+  /**
+   * Map of skill name -> script filename in `skills/`, e.g.
+   * {"collect": "main.py"} or {"collect": "main.ts"}. The file extension
+   * decides which runtime the platform executes the script in.
+   */
+  skills: z.record(z.string().min(1), skillScriptSchema).default({}),
+  /**
+   * npm packages the TypeScript/JavaScript skills import beyond Node's
+   * standard library. Only packages on the platform's allowlist are
+   * installed — `kohala validate` and `kohala deploy` refuse anything else
+   * offline, before the deploy request. Python skills never use this: pip
+   * packages are not installable from the CLI deploy path.
+   */
+  dependencies: dependenciesSchema,
   /** Cron expression. Used only on deploy; local runs are always manual. */
   schedule: z.string().min(1).optional(),
   caps: capsSchema,
   validators: z.array(validatorSchema).default([])
 }).strict();
+function crossFieldProblems(manifest) {
+  const problems = [];
+  if (manifest.runtimeMode === "wrap") {
+    for (const [name, filename] of Object.entries(manifest.skills)) {
+      if (languageForEntrypointFile(filename) === null) {
+        problems.push(
+          `skills.${name}: "${filename}" must be a script the platform can run in wrap mode \u2014 one of: ${SCRIPT_FILE_EXTENSIONS.join(", ")}`
+        );
+      }
+    }
+  }
+  if (manifest.dependencies.length > 0 && !hasNodeSkill(manifest.skills)) {
+    problems.push(
+      `dependencies: declares npm package(s) (${manifest.dependencies.join(", ")}) but no skill is a TypeScript/JavaScript entrypoint \u2014 only those install npm packages (hint: use a ${ENTRYPOINT_EXTENSIONS.node.join(" / ")} skill script, or remove "dependencies")`
+    );
+  }
+  return problems;
+}
 
 // src/cli/init.ts
 function templatesDir() {
@@ -83,9 +154,11 @@ function templatesDir() {
     path.resolve(here, "..", "..", "..", "templates")
   ];
   for (const candidate of candidates) {
-    if (fs.existsSync(path.join(candidate, "kohala.json"))) return candidate;
+    if (fs.existsSync(path.join(candidate, "python", "kohala.json"))) return candidate;
   }
-  throw new Error(`Could not locate the devkit templates directory (looked in: ${candidates.join(", ")})`);
+  throw new Error(
+    `Could not locate the devkit templates directory (looked in: ${candidates.join(", ")})`
+  );
 }
 function copyTemplates(sourceDir, targetDir, agentName) {
   fs.mkdirSync(targetDir, { recursive: true });
@@ -101,7 +174,7 @@ function copyTemplates(sourceDir, targetDir, agentName) {
   }
 }
 function registerInitCommand(program2) {
-  program2.command("init").argument("<name>", "agent name (also the directory name)").description("Scaffold a new agent: kohala.json, a working skill, and the local SDK").action((name) => {
+  program2.command("init").argument("<name>", "agent name (also the directory name)").option("--language <language>", "scaffold language: python or ts", "python").description("Scaffold a new agent: kohala.json, a working skill, and the local SDK").action((name, options) => {
     const nameCheck = manifestSchema.shape.name.safeParse(name);
     if (!nameCheck.success) {
       throw new Error(
@@ -112,7 +185,12 @@ function registerInitCommand(program2) {
     if (fs.existsSync(targetDir)) {
       throw new Error(`${targetDir} already exists \u2014 pick a new name or remove the directory.`);
     }
-    copyTemplates(templatesDir(), targetDir, name);
+    const language = options.language.toLowerCase();
+    const template = language === "ts" || language === "typescript" ? "typescript" : language === "py" || language === "python" ? "python" : null;
+    if (!template) {
+      throw new Error(`Unsupported language "${options.language}". Choose "python" or "ts".`);
+    }
+    copyTemplates(path.join(templatesDir(), template), targetDir, name);
     console.log(pc.green(`Created agent "${name}" in ${targetDir}`));
     console.log("");
     console.log("Next steps:");
@@ -143,7 +221,8 @@ var FIELD_HINTS = {
   charter: "write the agent's mission as a non-empty string",
   toolAllowlist: 'list allowed tool names, e.g. ["s3.put", "http.post_json"]',
   runtimeMode: 'must be "wrap" (script wrapper) or "llm" (tool-use loop)',
-  skills: 'map skill name to script filename, e.g. {"collect": "main.py"}',
+  skills: 'map skill name to script filename, e.g. {"collect": "main.py"} or {"collect": "main.ts"}',
+  dependencies: 'list npm packages the TypeScript/JavaScript skills import, e.g. ["zod"]',
   schedule: 'use a cron expression like "0 9 * * *" (only used on deploy)',
   caps: "set caps.perRunTokens and caps.perDayTokens as positive integers",
   validators: 'each validator needs a "type" of "shape", "freshness" or "invariant"'
@@ -187,6 +266,10 @@ function loadManifest(agentDir) {
   if (!result.success) {
     throw new ManifestError(`${filePath} failed validation`, formatManifestIssues(result.error));
   }
+  const crossField = crossFieldProblems(result.data);
+  if (crossField.length > 0) {
+    throw new ManifestError(`${filePath} failed validation`, crossField);
+  }
   return result.data;
 }
 
@@ -399,49 +482,112 @@ function unknownToolIds(tools) {
   return tools.filter((t) => !KNOWN_TOOL_IDS.has(t));
 }
 
+// src/manifest/npm-packages.ts
+var CLI_FRAMEWORK = "custom";
+var ALLOWED_NPM_PACKAGES = [
+  "zod",
+  "openai",
+  "@anthropic-ai/sdk",
+  "ai",
+  "@ai-sdk/openai",
+  "@ai-sdk/anthropic",
+  "date-fns",
+  "cheerio",
+  "js-yaml"
+];
+function normalizeNpmName(name) {
+  return name.trim().toLowerCase();
+}
+function rejectedNpmPackages(dependencies) {
+  const allowed = new Set(ALLOWED_NPM_PACKAGES.map(normalizeNpmName));
+  const seen = /* @__PURE__ */ new Set();
+  const rejected = [];
+  for (const dependency of dependencies) {
+    const normalized = normalizeNpmName(dependency);
+    if (!normalized || allowed.has(normalized) || seen.has(normalized)) continue;
+    seen.add(normalized);
+    rejected.push(dependency.trim());
+  }
+  return rejected;
+}
+function npmAllowlistMessage(rejected) {
+  return `unsupported npm dependencies for framework "${CLI_FRAMEWORK}": ${rejected.join(", ")}. Supported packages: ${ALLOWED_NPM_PACKAGES.map(normalizeNpmName).sort().join(", ")}`;
+}
+
 // src/cli/validate.ts
 function registerValidateCommand(program2) {
   program2.command("validate").argument("<agent>", "agent directory (containing kohala.json)").option(
     "--allow-unknown-tools",
     "do not fail on tool ids missing from the bundled catalog snapshot"
-  ).description("Validate an agent's kohala.json and print precise errors").action((agent, options) => {
-    const agentDir = path3.resolve(process.cwd(), agent);
-    try {
-      const manifest = loadManifest(agentDir);
-      const unknown = unknownToolIds(manifest.toolAllowlist);
-      if (unknown.length > 0) {
-        const msg = `toolAllowlist contains tool id(s) not in the Kohala tool catalog: ` + unknown.join(", ");
-        if (options.allowUnknownTools) {
-          console.warn(pc2.yellow(`warning: ${msg}`));
-        } else {
-          console.error(pc2.red(msg));
-          console.error(
+  ).option(
+    "--allow-unknown-packages",
+    "do not fail on npm packages missing from the bundled allowlist snapshot"
+  ).description("Validate an agent's kohala.json and print precise errors").action(
+    (agent, options) => {
+      const agentDir = path3.resolve(process.cwd(), agent);
+      try {
+        const manifest = loadManifest(agentDir);
+        const unknown = unknownToolIds(manifest.toolAllowlist);
+        if (unknown.length > 0) {
+          const msg = `toolAllowlist contains tool id(s) not in the Kohala tool catalog: ` + unknown.join(", ");
+          if (options.allowUnknownTools) {
+            console.warn(pc2.yellow(`warning: ${msg}`));
+          } else {
+            console.error(pc2.red(msg));
+            console.error(
+              pc2.dim(
+                "  If these are new platform tools the bundled snapshot doesn't know yet, re-run with --allow-unknown-tools (the deploy endpoint will still verify against the live catalog)."
+              )
+            );
+            process.exitCode = 1;
+            return;
+          }
+        }
+        const rejected = rejectedNpmPackages(manifest.dependencies);
+        if (rejected.length > 0) {
+          const msg = npmAllowlistMessage(rejected);
+          if (options.allowUnknownPackages) {
+            console.warn(pc2.yellow(`warning: ${msg}`));
+          } else {
+            console.error(pc2.red(msg));
+            console.error(
+              pc2.dim(
+                "  The platform refuses these when the script is attached, so deploy would fail. Remove them, or re-run with --allow-unknown-packages if the bundled snapshot is stale (the deploy endpoint still enforces the live allowlist)."
+              )
+            );
+            process.exitCode = 1;
+            return;
+          }
+        }
+        console.log(pc2.green(`kohala.json for "${manifest.name}" is valid.`));
+        console.log(
+          pc2.dim(
+            `  runtimeMode=${manifest.runtimeMode} language=${summarizeLanguages(manifest.skills)} skills=${Object.keys(manifest.skills).length} validators=${manifest.validators.length} allowlist=[${manifest.toolAllowlist.join(", ")}]`
+          )
+        );
+        for (const skill of skillLanguages(manifest.skills)) {
+          console.log(
             pc2.dim(
-              "  If these are new platform tools the bundled snapshot doesn't know yet, re-run with --allow-unknown-tools (the deploy endpoint will still verify against the live catalog)."
+              `  skill "${skill.name}" \u2192 skills/${skill.scriptFilename} (${LANGUAGE_LABEL[skill.language]})`
             )
           );
+        }
+        if (manifest.dependencies.length > 0) {
+          console.log(pc2.dim(`  npm packages: ${manifest.dependencies.join(", ")}`));
+        }
+      } catch (error) {
+        if (error instanceof ManifestError) {
+          console.error(pc2.red(error.message));
+          for (const problem of error.problems) {
+            console.error(pc2.red(`  \u2022 ${problem}`));
+          }
           process.exitCode = 1;
           return;
         }
+        throw error;
       }
-      console.log(pc2.green(`kohala.json for "${manifest.name}" is valid.`));
-      console.log(
-        pc2.dim(
-          `  runtimeMode=${manifest.runtimeMode} skills=${Object.keys(manifest.skills).length} validators=${manifest.validators.length} allowlist=[${manifest.toolAllowlist.join(", ")}]`
-        )
-      );
-    } catch (error) {
-      if (error instanceof ManifestError) {
-        console.error(pc2.red(error.message));
-        for (const problem of error.problems) {
-          console.error(pc2.red(`  \u2022 ${problem}`));
-        }
-        process.exitCode = 1;
-        return;
-      }
-      throw error;
     }
-  });
+  );
 }
 
 // src/cli/run.ts
@@ -1556,6 +1702,7 @@ async function findPython() {
 }
 
 // src/emulator/runner.ts
+import { fileURLToPath as fileURLToPath2 } from "url";
 var MAX_REPAIR_ATTEMPTS = 2;
 function resolveSkill(manifest, requested) {
   const entries = Object.entries(manifest.skills);
@@ -1689,7 +1836,12 @@ async function runShift(options) {
       });
       if (!execution.ok) {
         if (meter.abortedWith?.code === "PER_RUN_TOKEN_CAP") {
-          return finish("aborted_per_run_token_cap", execution.stdout, [], meter.abortedWith.message);
+          return finish(
+            "aborted_per_run_token_cap",
+            execution.stdout,
+            [],
+            meter.abortedWith.message
+          );
         }
         return finish("error", execution.stdout, [], execution.errorDetail);
       }
@@ -1705,7 +1857,12 @@ async function runShift(options) {
       }
       repairReason = failures.map((failure) => `${failure.validator}: ${failure.detail}`).join("; ");
       if (attempt === MAX_REPAIR_ATTEMPTS) {
-        return finish("failed", execution.stdout, validatorResults, `validators failed after ${MAX_REPAIR_ATTEMPTS} repair attempts: ${repairReason}`);
+        return finish(
+          "failed",
+          execution.stdout,
+          validatorResults,
+          `validators failed after ${MAX_REPAIR_ATTEMPTS} repair attempts: ${repairReason}`
+        );
       }
     }
     throw new Error("repair loop exited without a result");
@@ -1727,10 +1884,29 @@ function recordValidatorResults(trace, runId, agent, results) {
   }
 }
 async function executeScript(options) {
-  const python = await findPython();
   const scriptPath = path8.join(options.agentDir, "skills", options.scriptFilename);
+  const extension = path8.extname(options.scriptFilename).toLowerCase();
+  let command;
+  let args;
+  if (extension === ".py") {
+    command = await findPython();
+    args = [scriptPath];
+  } else if (extension === ".ts" || extension === ".mts" || extension === ".cts") {
+    command = process.execPath;
+    const tsxCli = fileURLToPath2(import.meta.resolve("tsx/cli"));
+    args = [tsxCli, scriptPath];
+  } else if (extension === ".js" || extension === ".mjs" || extension === ".cjs") {
+    command = process.execPath;
+    args = [scriptPath];
+  } else {
+    return {
+      ok: false,
+      stdout: "",
+      errorDetail: `Unsupported skill script extension "${extension || "(none)"}". Use .py, .ts, .mts, .cts, .js, .mjs, or .cjs.`
+    };
+  }
   try {
-    const result = await execa2(python, [scriptPath], {
+    const result = await execa2(command, args, {
       cwd: options.agentDir,
       env: {
         KOHALA_RPC_URL: options.rpcUrl,
@@ -1760,11 +1936,7 @@ async function executeScript(options) {
 
 // src/cli/run.ts
 function registerRunCommand(program2) {
-  program2.command("run").argument("<agent>", "agent directory (containing kohala.json)").option("--local", "run against the local emulator (required for now)").option("--skill <name>", "which skill to run (defaults to the only skill)").option(
-    "--backend <backend>",
-    "memory backend for this run: file | postgres",
-    "file"
-  ).option("--url <url>", "postgres connection string (or set DATABASE_URL)").description("Run a shift against the local emulator").action(
+  program2.command("run").argument("<agent>", "agent directory (containing kohala.json)").option("--local", "run against the local emulator (required for now)").option("--skill <name>", "which skill to run (defaults to the only skill)").option("--backend <backend>", "memory backend for this run: file | postgres", "file").option("--url <url>", "postgres connection string (or set DATABASE_URL)").description("Run a shift against the local emulator").action(
     async (agent, options) => {
       if (!options.local) {
         throw new Error(
@@ -1787,7 +1959,13 @@ function registerRunCommand(program2) {
         console.log(
           pc3.cyan(`Running shift for "${manifest.name}" (${manifest.runtimeMode} mode)...`)
         );
-        const result = await runShift({ rootDir, agentDir, manifest, store, skill: options.skill });
+        const result = await runShift({
+          rootDir,
+          agentDir,
+          manifest,
+          store,
+          skill: options.skill
+        });
         console.log("");
         if (result.status === "succeeded") {
           console.log(pc3.green(`\u2714 Shift ${result.runId} succeeded`));
@@ -1798,7 +1976,9 @@ function registerRunCommand(program2) {
         console.log(pc3.dim(`  tokens used: ${result.totalTokens} (counted, never billed)`));
         for (const validator of result.validatorResults) {
           const mark = validator.passed ? pc3.green("passed") : pc3.red("failed");
-          console.log(pc3.dim(`  validator ${validator.validator}: `) + mark + pc3.dim(` \u2014 ${validator.detail}`));
+          console.log(
+            pc3.dim(`  validator ${validator.validator}: `) + mark + pc3.dim(` \u2014 ${validator.detail}`)
+          );
         }
         if (result.output.trim() !== "") {
           console.log("");
@@ -2243,6 +2423,9 @@ import pc8 from "picocolors";
 import fs12 from "fs";
 import path13 from "path";
 var DEFAULT_BASE_URL = "https://kohala.ai";
+function skillPayloadLanguage(payload) {
+  return payload.runtimeLanguage ?? "python";
+}
 function buildDeployPlan(manifest, agentDir) {
   const skills = Object.entries(manifest.skills).map(([name, scriptFilename]) => {
     const scriptPath = path13.join(agentDir, "skills", scriptFilename);
@@ -2251,11 +2434,16 @@ function buildDeployPlan(manifest, agentDir) {
         `Skill "${name}" points at ${scriptFilename}, but ${scriptPath} does not exist.`
       );
     }
+    const language = languageForEntrypointFile(scriptFilename) ?? "python";
     return {
       name,
       scriptFilename,
       description: `Skill "${name}" of agent "${manifest.name}"`,
-      code: fs12.readFileSync(scriptPath, "utf8")
+      code: fs12.readFileSync(scriptPath, "utf8"),
+      ...language === "node" ? {
+        runtimeLanguage: "node",
+        ...manifest.dependencies.length > 0 ? { scriptDependencies: manifest.dependencies } : {}
+      } : {}
     };
   });
   if (manifest.schedule && skills.length === 0) {
@@ -2280,6 +2468,17 @@ function buildDeployPlan(manifest, agentDir) {
     }
   };
 }
+function readableApiError(body) {
+  const raw = (body ?? "").trim();
+  try {
+    const parsed = JSON.parse(raw);
+    const parts = [parsed.error, parsed.message].filter((part) => typeof part === "string" && part.trim() !== "").map((part) => part.trim());
+    const unique = parts.filter((part, index) => parts.indexOf(part) === index);
+    if (unique.length > 0) return unique.join(" \u2014 ").slice(0, 1e3);
+  } catch {
+  }
+  return raw.slice(0, 500);
+}
 var DeployError = class extends Error {
   constructor(status, message) {
     super(message);
@@ -2326,7 +2525,7 @@ var KohalaClient = class {
       const text2 = await response.text();
       throw new DeployError(
         response.status,
-        `Kohala API error ${response.status} on ${method} ${apiPath}: ${text2.slice(0, 500)}`
+        `Kohala API error ${response.status} on ${method} ${apiPath}: ${readableApiError(text2)}`
       );
     }
     const text = await response.text();
@@ -2393,10 +2592,25 @@ var KohalaClient = class {
 
 // src/cli/deploy.ts
 function registerDeployCommand(program2) {
-  program2.command("deploy").argument("<agent>", "agent directory (containing kohala.json)").option("--dry-run", "print the payloads without sending anything").option("--base-url <url>", "API base URL", DEFAULT_BASE_URL).option("--run", "trigger a manual run after deploying").description("Deploy an agent to kohala.ai (idempotent on agent name)").action(
+  program2.command("deploy").argument("<agent>", "agent directory (containing kohala.json)").option("--dry-run", "print the payloads without sending anything").option("--base-url <url>", "API base URL", DEFAULT_BASE_URL).option("--run", "trigger a manual run after deploying").option(
+    "--allow-unknown-packages",
+    "do not fail on npm packages missing from the bundled allowlist snapshot"
+  ).description("Deploy an agent to kohala.ai (idempotent on agent name)").action(
     async (agent, options) => {
       const agentDir = path14.resolve(process.cwd(), agent);
       const manifest = loadManifest(agentDir);
+      const rejected = rejectedNpmPackages(manifest.dependencies);
+      if (rejected.length > 0) {
+        const message = npmAllowlistMessage(rejected);
+        if (options.allowUnknownPackages) {
+          console.warn(pc8.yellow(`warning: ${message}`));
+        } else {
+          throw new Error(
+            `${message}
+  The platform refuses these when the script is attached, so this deploy would fail. Remove them, or re-run with --allow-unknown-packages if the bundled snapshot is stale (the deploy endpoint still enforces the live allowlist).`
+          );
+        }
+      }
       const plan = buildDeployPlan(manifest, agentDir);
       if (options.dryRun) {
         console.log(pc8.cyan("Dry run \u2014 nothing will be sent. Deploy plan:"));
@@ -2405,7 +2619,11 @@ function registerDeployCommand(program2) {
         console.log(JSON.stringify(plan.agent, null, 2));
         for (const skill of plan.skills) {
           console.log("");
-          console.log(pc8.bold(`2. POST /api/v1/agents/:id/skills \u2014 "${skill.name}"`));
+          console.log(
+            pc8.bold(
+              `2. POST /api/v1/agents/:id/skills \u2014 "${skill.name}" (${LANGUAGE_LABEL[skillPayloadLanguage(skill)]})`
+            )
+          );
           console.log(
             JSON.stringify(
               { ...skill, code: `<${Buffer.byteLength(skill.code)} bytes of ${skill.scriptFilename}>` },
@@ -2459,7 +2677,12 @@ function registerDeployCommand(program2) {
       );
       for (const skill of plan.skills) {
         await client.upsertSkill(upserted.id, skill);
-        console.log(pc8.green(`  \u2714 skill "${skill.name}" uploaded (${skill.scriptFilename})`));
+        const packages = skill.scriptDependencies?.length ? `, npm: ${skill.scriptDependencies.join(", ")}` : "";
+        console.log(
+          pc8.green(
+            `  \u2714 skill "${skill.name}" uploaded (${skill.scriptFilename}, ${LANGUAGE_LABEL[skillPayloadLanguage(skill)]}${packages})`
+          )
+        );
       }
       if (plan.agent.agentScheduleCron) {
         const filenames = plan.skills.map((skill) => skill.scriptFilename);