buckyos 0.7.160 → 0.7.162

package/cli/dist/cli.mjs

@@ -2,7 +2,7 @@ import process from "node:process";
 import { fileURLToPath } from "node:url";
 import * as nodePath from "node:path";
 import { resolve as resolve$5, dirname as dirname$3 } from "node:path";
-import { BuckyOSSDK, RuntimeType, buckyos, namelib, VerifyHubClient, createAppInstanceId, parseSessionTokenClaims, ndn, verifyBundle, controlSkeleton, aiwsContentDigest, AIWS_MANIFEST_VERSION, AIWS_MANIFEST_FILE, taskMgrTaskEventPath, ndm_proxy, objectUrl as objectUrl$1, ExecutorCommandStream, watchControl, buildControl, pullControl, exportBundle, NfspClient, AiwsSourceError } from "buckyos/node";
+import { BuckyOSSDK, RuntimeType, buckyos, namelib, VerifyHubClient, createAppInstanceId, parseSessionTokenClaims, ndn, verifyBundle, controlSkeleton, aiwsContentDigest, AIWS_MANIFEST_VERSION, AIWS_MANIFEST_FILE, taskMgrTaskEventPath, ndm_proxy, objectUrl as objectUrl$1, ExecutorCommandStream, watchControl, buildControl, pullControl, exportBundle, NfspClient, AiwsSourceError, packBuildFiles, templateDir, isSourcePath } from "buckyos/node";
 import * as provisionSdk from "buckyos/provision";
 import { createHash } from "node:crypto";
 import { readFile, writeFile, readdir, stat, lstat, realpath, mkdtemp, rename, rm, mkdir, chmod, symlink, copyFile, open } from "node:fs/promises";
@@ -4499,7 +4499,11 @@ async function verifyAiwsPayload(tarGz) {
   if (errors.length > 0) {
     throw invalid("aiws", `aiws bundle: ${errors.map((d) => `${d.file}: ${d.message}`).join("; ")}`);
   }
-  return { manifest_version: checked.manifest.manifest_version, controls: checked.manifest.controls.map((c) => ({ ident: c.ident, kind: c.kind, version: c.version, digest: c.digest })) };
+  return {
+    manifest_version: checked.manifest.manifest_version,
+    controls: checked.manifest.controls.map((c) => ({ ident: c.ident, kind: c.kind, version: c.version, digest: c.digest })),
+    templates: checked.manifest.workspace_templates.map((t) => ({ id: t.id, title: t.title, digest: t.digest, requires: t.requires }))
+  };
 }
 async function validateSnapshot(distDir, appDoc, packageMeta) {
   const payloads = /* @__PURE__ */ new Map();
@@ -5238,7 +5242,7 @@ function validateContentHandlers(value, permissions) {
   }
   return value;
 }
-const PACKAGE_VERSION = "0.7.160";
+const PACKAGE_VERSION = "0.7.162";
 const TOOL_VERSION = PACKAGE_VERSION;
 const SDK_VERSION = PACKAGE_VERSION;
 const PROTOCOL_VERSION = "1";
@@ -5332,7 +5336,12 @@ function createPikgModule(dependencies = {}) {
             type: "string"
           },
           { name: "version", description: "Initial App version", type: "string" },
-          { name: "app-did", property: "app_did", description: "Explicit App DID", type: "string" }
+          { name: "app-did", property: "app_did", description: "Explicit App DID", type: "string" },
+          {
+            name: "composite",
+            description: "aiws-controls: start the package with a composite control (a panel of Blocks) instead of a declarative one",
+            type: "boolean"
+          }
         ],
         inputSchema: {
           type: "object",
@@ -5343,7 +5352,8 @@ function createPikgModule(dependencies = {}) {
             kind: { type: "string", enum: APP_KINDS },
             source: { type: "string", minLength: 1 },
             version: { type: "string", minLength: 1 },
-            app_did: { type: "string", minLength: 1 }
+            app_did: { type: "string", minLength: 1 },
+            composite: { type: "boolean" }
           },
           additionalProperties: false
         },
@@ -5358,7 +5368,8 @@ function createPikgModule(dependencies = {}) {
           "buckyos pikg init .",
           "buckyos --non-interactive pikg init . --owner did:bns:root --kind static-web --source ./web/dist",
           "buckyos --non-interactive pikg init . --owner did:bns:root --kind agent-skills --source ./skills",
-          "buckyos --non-interactive pikg init . --owner did:bns:alice --kind aiws-controls --source ./aiws"
+          "buckyos --non-interactive pikg init . --owner did:bns:alice --kind aiws-controls --source ./aiws",
+          "buckyos --non-interactive pikg init . --owner did:bns:alice --kind aiws-controls --source ./aiws --composite"
         ],
         handler: async (ctx, input) => await initCommand(ctx, input, docker)
       },
@@ -5601,7 +5612,7 @@ async function initCommand(ctx, input, docker) {
       if (!isHostError(error, "NotFound"))
         throw error;
       if (kind === "aiws-controls") {
-        await writeAiwsSkeleton(absoluteSource, owner, name);
+        await writeAiwsSkeleton(absoluteSource, owner, name, input.composite === true);
         sourceSummary2.skeleton = true;
       } else {
         await ctx.io.stderr(`warning: source does not exist yet: ${sourceSummary2.path}
@@ -5666,8 +5677,9 @@ async function initCommand(ctx, input, docker) {
     next_command: `buckyos pikg build ${metaDir}`
   };
 }
-async function writeAiwsSkeleton(dir, ownerDid, name) {
-  const files = controlSkeleton({ authorDid: ownerDid, name, title: name });
+async function writeAiwsSkeleton(dir, ownerDid, name, composite) {
+  const kind = composite ? "composite" : "declarative";
+  const files = controlSkeleton({ authorDid: ownerDid, name, title: name, kind });
   const encoder = new TextEncoder();
   const host2 = getHost();
   await host2.mkdir(join(dir, "controls", name), { recursive: true });
@@ -5677,8 +5689,8 @@ async function writeAiwsSkeleton(dir, ownerDid, name) {
   const manifest = {
     manifest_version: AIWS_MANIFEST_VERSION,
     purpose: "aiws",
-    host_api: { declarative: 1 },
-    controls: [{ ident: `${ownerDid}#${name}`, name, kind: "declarative", version: 1, digest, dir: `controls/${name}/`, title: name }],
+    host_api: composite ? {} : { declarative: 1 },
+    controls: [{ ident: `${ownerDid}#${name}`, name, kind, version: 1, digest, dir: `controls/${name}/`, title: name }],
     workspace_templates: []
   };
   await host2.writeTextFile(join(dir, AIWS_MANIFEST_FILE), `${JSON.stringify(manifest, null, 2)}
@@ -11577,6 +11589,25 @@ async function sourceErrors(run) {
 function list(input, key) {
   return requiredInputString(input, key).split(",").map((s) => s.trim()).filter(Boolean);
 }
+const IDENT = /^did:[a-z0-9]+:[^/#\s]+#[a-z0-9][a-z0-9._-]{0,63}$/;
+async function migrationFile(ctx, path) {
+  const host2 = getHost();
+  let value;
+  try {
+    value = JSON.parse(await host2.readTextFile(host2.path.resolve(ctx.cwd, path)));
+  } catch (error) {
+    throw new UsageError("AIWS_USAGE", `--migration ${path}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  const shape = `--migration ${path}: { "<author_did>#<name>": { config?, bindings?, slots?, events? } }`;
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new UsageError("AIWS_USAGE", shape);
+  for (const [ident, m] of Object.entries(value)) {
+    if (!IDENT.test(ident) || !m || typeof m !== "object" || Array.isArray(m) || Object.keys(m).some((k) => !["config", "bindings", "slots", "events"].includes(k))) {
+      throw new UsageError("AIWS_USAGE", `${shape} (at ${ident})`);
+    }
+  }
+  return value;
+}
 const LOCAL_STATE = ".aiws-build.json";
 async function isLocalDir(path) {
   try {
@@ -11589,25 +11620,42 @@ async function localFiles(dir) {
   const host2 = getHost();
   const files = [];
   const problems = [];
-  let total = 0;
-  for (const entry of await host2.readDir(dir)) {
-    if (entry.name.startsWith("."))
-      continue;
-    if (!entry.isFile) {
-      problems.push({ file: entry.name, severity: "error", message: "a control source folder is flat: move files out of sub-folders" });
-      continue;
+  const walk = async (folder, prefix, depth) => {
+    for (const entry of await host2.readDir(folder)) {
+      if (entry.name.startsWith("."))
+        continue;
+      const name = `${prefix}${entry.name}`;
+      if (entry.isDirectory) {
+        if (depth >= 8)
+          problems.push({ file: name, severity: "error", message: "sub-folders nest at most 8 levels" });
+        else
+          await walk(host2.path.join(folder, entry.name), `${name}/`, depth + 1);
+      } else if (entry.isFile)
+        files.push({ name, bytes: await host2.readFile(host2.path.join(folder, entry.name)) });
+      else
+        problems.push({ file: name, severity: "error", message: "only files and folders belong to a control source" });
     }
-    const bytes = await host2.readFile(host2.path.join(dir, entry.name));
-    total += bytes.length;
-    files.push({ name: entry.name, base64: btoa(Array.from(bytes, (b) => String.fromCharCode(b)).join("")) });
-  }
+  };
+  await walk(dir, "", 0);
   if (files.length === 0)
     problems.push({ file: "", severity: "error", message: `${dir} holds no files` });
-  if (total > 4 * 1024 * 1024)
-    problems.push({ file: "", severity: "error", message: "a control is limited to 4 MiB per build from a local folder" });
   if (problems.length > 0)
     throw new ToolError("BUILD_FAILED", `BUILD_FAILED: ${problems.map((p) => `${p.file}: ${p.message}`).join("; ")}`, void 0, false, { data: { diagnostics: problems } });
-  return files.sort((a, b) => a.name.localeCompare(b.name));
+  return files.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+}
+function sourceUploader(ctx) {
+  return async (name, bytes) => {
+    const bucket = `user/aiworkspace/${ctx.principal.id}/exports`;
+    const key = `aiws-src/${Date.now()}-${name.replaceAll("/", "_")}`;
+    const url = `${gatewayOrigin$2(ctx.connection.endpoint)}/bucket/v1/${bucket}/${key.split("/").map(encodeURIComponent).join("/")}`;
+    const response = await fetch(url, { method: "PUT", headers: { Authorization: `Bearer ${await sessionToken(ctx)}` }, body: new Blob([bytes]), signal: ctx.signal });
+    if (!response.ok)
+      throw new ToolError("AIWS_UPLOAD_FAILED", `upload of ${name}: HTTP ${response.status} ${await response.text().catch(() => "")}`);
+    const put = await response.json();
+    if (!put.obj_id)
+      throw new ToolError("AIWS_UPLOAD_FAILED", `upload of ${name}: the bucket answered no obj_id`);
+    return put.obj_id;
+  };
 }
 async function localState(dir) {
   try {
@@ -11620,11 +11668,12 @@ async function buildLocal(ctx, ws, dir, opts) {
   const state = await localState(dir);
   const result = await aiws(ctx, "ext.build", {
     workspace_id: ws,
-    files: await localFiles(dir),
+    files: await sourceErrors(async () => packBuildFiles(await localFiles(dir), sourceUploader(ctx))),
     ...opts.folderId ? { folder_id: opts.folderId } : {},
     ...state && state.workspace_id === ws ? { expect: { def_rev: state.def_rev, dir_rev: state.dir_rev } } : {},
     ...opts.force ? { force: true } : {},
-    ...opts.dryRun ? { dry_run: true } : {}
+    ...opts.dryRun ? { dry_run: true } : {},
+    ...opts.migration ? { migration: opts.migration } : {}
   });
   if (!opts.dryRun && typeof result.def_entity_id === "string" && typeof result.def_rev === "number") {
     await getHost().writeTextFile(getHost().path.join(dir, LOCAL_STATE), `${JSON.stringify({ workspace_id: ws, def_entity_id: result.def_entity_id, def_rev: result.def_rev, dir_rev: result.dir_rev ?? 0, ident: result.ident, at: (/* @__PURE__ */ new Date()).toISOString() }, null, 2)}
@@ -11635,7 +11684,7 @@ async function buildLocal(ctx, ws, dir, opts) {
 const buildCommand = {
   verb: "build",
   summary: "Build a control from its source folder (local, or in the Zone; component.json + files) into a Workspace; instances update, a failure commits nothing",
-  description: "The folder is a local folder (when it exists here; its files are sent inline, ≤ 4 MiB) or a Zone path (e.g. /home/alice/AI Workspace/Demo/controls/kpi-card; --zone-path forces it), flat. The base of the last build or pull is kept in its .aiws-build.json; building over a newer Workspace version is refused (pull first, or --force). --watch rebuilds on every change until interrupted.",
+  description: 'The folder is a local folder (when it exists here; its files are sent inline, and past 4 MiB per build the largest are uploaded to your exports bucket and sent by reference) or a Zone path (e.g. /home/alice/AI Workspace/Demo/controls/kpi-card; --zone-path forces it); sub-folders are part of the source (file names are relative paths). The base of the last build or pull is kept in its .aiws-build.json; building over a newer Workspace version is refused (pull first, or --force). --watch rebuilds on every change until interrupted. A build that narrows what instances rely on (a binding renamed, a slot moved, an event dropped) takes --migration, a JSON file { "<author_did>#<name>": Migration } (as ext-upgrade).',
   positionals: [{ name: "dir", description: "Local folder, or Zone path of the control source folder", required: true }],
   options: [
     WORKSPACE_OPTION,
@@ -11643,9 +11692,10 @@ const buildCommand = {
     { name: "watch", property: "watch", description: "Rebuild whenever the folder changes", type: "boolean" },
     { name: "dry-run", property: "dry_run", description: "Check only: diagnostics, nothing committed", type: "boolean" },
     { name: "force", property: "force", description: "Build over whatever the Workspace holds now", type: "boolean" },
-    { name: "zone-path", property: "zone_path", description: "Treat the folder as a Zone path even if a local folder has that name", type: "boolean" }
+    { name: "zone-path", property: "zone_path", description: "Treat the folder as a Zone path even if a local folder has that name", type: "boolean" },
+    { name: "migration", property: "migration", description: 'JSON file { "<author_did>#<name>": Migration } rewriting the instances of a build that narrows the contract', type: "string" }
   ],
-  inputSchema: workspaceInput({ dir: { type: "string", minLength: 1 }, folder_id: { type: "string" }, watch: { type: "boolean" }, dry_run: { type: "boolean" }, force: { type: "boolean" }, zone_path: { type: "boolean" } }, ["dir"]),
+  inputSchema: workspaceInput({ dir: { type: "string", minLength: 1 }, folder_id: { type: "string" }, watch: { type: "boolean" }, dry_run: { type: "boolean" }, force: { type: "boolean" }, zone_path: { type: "boolean" }, migration: { type: "string" } }, ["dir"]),
   outputSchema: OBJECT_OUTPUT,
   resultSchemaVersion: 1,
   access: { mode: "fixed", level: "write" },
@@ -11655,7 +11705,8 @@ const buildCommand = {
   handler: async (ctx, input) => {
     const ws = requiredInputString(input, "workspace_id");
     const dir = requiredInputString(input, "dir");
-    const opts = { folderId: inputString(input, "folder_id"), force: input.force === true, dryRun: input.dry_run === true };
+    const migration = inputString(input, "migration");
+    const opts = { folderId: inputString(input, "folder_id"), force: input.force === true, dryRun: input.dry_run === true, upload: sourceUploader(ctx), ...migration ? { migration: await migrationFile(ctx, migration) } : {} };
     if (input.zone_path !== true && await isLocalDir(getHost().path.resolve(ctx.cwd, dir))) {
       const local = getHost().path.resolve(ctx.cwd, dir);
       if (input.watch === true)
@@ -11707,7 +11758,8 @@ const pullCommand = {
       const fetchAsset = assetFetcher(ctx);
       const files = [];
       for (const f of control.files) {
-        const target = host2.path.join(out, f.name);
+        const target = host2.path.join(out, ...f.name.split("/"));
+        await host2.mkdir(host2.path.dirname(target), { recursive: true });
         if (f.text !== void 0)
           await host2.writeTextFile(target, f.text);
         else
@@ -11741,6 +11793,57 @@ async function uploadPackage(ctx, path) {
     throw new ToolError("AIWS_UPLOAD_FAILED", `upload of ${path}: HTTP ${response.status} ${await response.text().catch(() => "")}`);
   return { bucket_id, key };
 }
+const PACKAGE_INPUT = { name: { type: "string" }, version: { type: "string" }, owner: { type: "string" }, pikg: { type: "boolean" }, install: { type: "boolean" } };
+function packageOptions(nameDefault) {
+  return [
+    { name: "name", property: "name", description: `Package name (default: ${nameDefault})`, type: "string" },
+    { name: "version", property: "version", description: "Package version (default 0.1.0)", type: "string" },
+    { name: "owner", property: "owner", description: "Owner DID of the package (default did:bns:<you>)", type: "string" },
+    { name: "pikg", property: "pikg", description: "Also pack the bundle as an aiws PIKG", type: "boolean" },
+    { name: "install", property: "install", description: "Pack, then install into your AI Workspace library (dev mode)", type: "boolean" }
+  ];
+}
+const fromBase64 = (text2) => Uint8Array.from(atob(text2), (c) => c.charCodeAt(0));
+async function writeBundle(out, files) {
+  const host2 = getHost();
+  const root = host2.path.join(out, "aiws");
+  await host2.remove(root, { recursive: true }).catch(() => void 0);
+  for (const [path, bytes] of files) {
+    const target = host2.path.join(root, path);
+    await host2.mkdir(host2.path.dirname(target), { recursive: true });
+    await host2.writeFile(target, bytes);
+  }
+  return root;
+}
+async function packBundle(ctx, input, out, defaultName, result) {
+  if (input.pikg !== true && input.install !== true)
+    return result;
+  const host2 = getHost();
+  const name = inputString(input, "name") ?? defaultName;
+  const owner = inputString(input, "owner") ?? `did:bns:${ctx.principal.id}`;
+  const version = inputString(input, "version") ?? "0.1.0";
+  const appJson = host2.path.join(out, "dapp_meta", "app.json");
+  const existing = await host2.readTextFile(appJson).then((t) => JSON.parse(t)).catch(() => null);
+  if (!existing) {
+    await pikgVerb(ctx, "init", { project_dir: out, name, owner, kind: "aiws-controls", source: "./aiws", version });
+  } else if (inputString(input, "version") && existing.version !== version) {
+    await host2.writeTextFile(appJson, `${JSON.stringify({ ...existing, version }, null, 2)}
+`);
+    const pikgJson = host2.path.join(out, "dapp_meta", "pikg.json");
+    const meta = JSON.parse(await host2.readTextFile(pikgJson));
+    await host2.writeTextFile(pikgJson, `${JSON.stringify({ ...meta, pikg_file: `${existing.name}-${version}.pikg` }, null, 2)}
+`);
+  }
+  await pikgVerb(ctx, "build", { meta_dir: host2.path.join(out, "dapp_meta") });
+  const packed = await pikgVerb(ctx, "pack", { dist_dir: host2.path.join(out, "dapp_dist") });
+  const pikgPath = String(packed.pikg_path);
+  result.pikg = pikgPath;
+  if (input.install !== true)
+    return result;
+  result.install = await aiws(ctx, "ext.install", { pikg: await uploadPackage(ctx, pikgPath), mode: "dev" });
+  return result;
+}
+const controlSummary = (controls) => controls.map((c) => ({ ident: c.ident, kind: c.kind, version: c.version, digest: c.digest }));
 const extExportCommand = {
   verb: "ext-export",
   summary: "Export Workspace controls as a bundle in a local folder; optionally pack it as an aiws PIKG and install it into your library",
@@ -11749,13 +11852,9 @@ const extExportCommand = {
   options: [
     WORKSPACE_OPTION,
     { name: "out", property: "out", description: "Local folder to write into (created)", type: "string", required: true },
-    { name: "name", property: "name", description: "Package name (default: the first control’s)", type: "string" },
-    { name: "version", property: "version", description: "Package version (default 0.1.0)", type: "string" },
-    { name: "owner", property: "owner", description: "Owner DID of the package (default did:bns:<you>)", type: "string" },
-    { name: "pikg", property: "pikg", description: "Also pack the bundle as an aiws PIKG", type: "boolean" },
-    { name: "install", property: "install", description: "Pack, then install into your AI Workspace library (dev mode)", type: "boolean" }
+    ...packageOptions("the first control’s")
   ],
-  inputSchema: workspaceInput({ defs: { type: "string", minLength: 1 }, out: { type: "string", minLength: 1 }, name: { type: "string" }, version: { type: "string" }, owner: { type: "string" }, pikg: { type: "boolean" }, install: { type: "boolean" } }, ["defs", "out"]),
+  inputSchema: workspaceInput({ defs: { type: "string", minLength: 1 }, out: { type: "string", minLength: 1 }, ...PACKAGE_INPUT }, ["defs", "out"]),
   outputSchema: OBJECT_OUTPUT,
   resultSchemaVersion: 1,
   access: { mode: "fixed", level: "write" },
@@ -11763,97 +11862,314 @@ const extExportCommand = {
   requiresSession: true,
   examples: ["buckyos aiws ext-export def_abc,def_xyz --workspace ws_abc --out ./kpi-pack --install"],
   handler: async (ctx, input) => {
-    const ws = requiredInputString(input, "workspace_id");
-    const host2 = getHost();
-    const out = host2.path.resolve(ctx.cwd, requiredInputString(input, "out"));
-    const bundle = await exportBundle(extRpc(ctx), ws, list(input, "defs"), assetFetcher(ctx));
-    const root = host2.path.join(out, "aiws");
-    await host2.remove(root, { recursive: true }).catch(() => void 0);
-    for (const [path, bytes] of bundle.files) {
-      const target = host2.path.join(root, path);
-      await host2.mkdir(host2.path.dirname(target), { recursive: true });
-      await host2.writeFile(target, bytes);
-    }
-    const result = { ok: true, bundle: root, controls: bundle.manifest.controls.map((c) => ({ ident: c.ident, kind: c.kind, version: c.version, digest: c.digest })) };
-    if (input.pikg !== true && input.install !== true)
-      return result;
-    const name = inputString(input, "name") ?? bundle.manifest.controls[0]?.name.replace(/[._]/g, "-") ?? "controls";
-    const owner = inputString(input, "owner") ?? `did:bns:${ctx.principal.id}`;
-    const version = inputString(input, "version") ?? "0.1.0";
-    const appJson = host2.path.join(out, "dapp_meta", "app.json");
-    const existing = await host2.readTextFile(appJson).then((t) => JSON.parse(t)).catch(() => null);
-    if (!existing) {
-      await pikgVerb(ctx, "init", { project_dir: out, name, owner, kind: "aiws-controls", source: "./aiws", version });
-    } else if (inputString(input, "version") && existing.version !== version) {
-      await host2.writeTextFile(appJson, `${JSON.stringify({ ...existing, version }, null, 2)}
-`);
-      const pikgJson = host2.path.join(out, "dapp_meta", "pikg.json");
-      const meta = JSON.parse(await host2.readTextFile(pikgJson));
-      await host2.writeTextFile(pikgJson, `${JSON.stringify({ ...meta, pikg_file: `${existing.name}-${version}.pikg` }, null, 2)}
-`);
-    }
-    await pikgVerb(ctx, "build", { meta_dir: host2.path.join(out, "dapp_meta") });
-    const packed = await pikgVerb(ctx, "pack", { dist_dir: host2.path.join(out, "dapp_dist") });
-    const pikgPath = String(packed.pikg_path);
-    result.pikg = pikgPath;
-    if (input.install !== true)
-      return result;
-    result.install = await aiws(ctx, "ext.install", { pikg: await uploadPackage(ctx, pikgPath), mode: "dev" });
-    return result;
+    const out = getHost().path.resolve(ctx.cwd, requiredInputString(input, "out"));
+    const bundle = await exportBundle(extRpc(ctx), requiredInputString(input, "workspace_id"), list(input, "defs"), assetFetcher(ctx));
+    const result = { ok: true, bundle: await writeBundle(out, bundle.files), controls: controlSummary(bundle.manifest.controls) };
+    return packBundle(ctx, input, out, bundle.manifest.controls[0]?.name.replace(/[._]/g, "-") ?? "controls", result);
+  }
+};
+const extUpgradeCommand = {
+  verb: "ext-upgrade",
+  summary: "Upgrade controls a Workspace imported from your library to the version your library holds now (one Commit; instances keep their overrides and content)",
+  description: 'Each definition is rebuilt from its package in your library (--pkg, or the package it was imported from), with what it builds on from the same package, dependencies first. A definition built locally since its import is refused (EXT_LOCAL_CHANGES; the error data lists the changed files) unless --force. A version that narrows what instances rely on needs --migration, a JSON file { "<author_did>#<name>": Migration } keyed by identity (config / bindings { rename, drop, fill }, slots { rename, move }, events { rename, drop }); --dry-run answers what it would write on each instance. Across Zones: `aiws library bundle <pkg_id> --out <file>` in the Zone of the library, then `aiws ext-import --bundle <file> --upgrade` in the Zone of the Workspace.',
+  positionals: [{ name: "defs", description: "Definition (buckyos.block-def) ids, comma-separated", required: true }],
+  options: [
+    WORKSPACE_OPTION,
+    { name: "pkg", property: "pkg_id", description: "Library package to upgrade from (default: the one each definition was imported from)", type: "string" },
+    { name: "migration", property: "migration", description: 'JSON file { "<author_did>#<name>": Migration } rewriting the instances of a narrowing version', type: "string" },
+    { name: "dry-run", property: "dry_run", description: "Check only: the plan per instance, nothing committed", type: "boolean" },
+    { name: "force", property: "force", description: "Upgrade over local changes (they are replaced)", type: "boolean" }
+  ],
+  inputSchema: workspaceInput({ defs: { type: "string", minLength: 1 }, pkg_id: { type: "string" }, migration: { type: "string" }, dry_run: { type: "boolean" }, force: { type: "boolean" } }, ["defs"]),
+  outputSchema: OBJECT_OUTPUT,
+  resultSchemaVersion: 1,
+  access: { mode: "fixed", level: "write" },
+  asyncMode: "sync",
+  requiresSession: true,
+  examples: ["buckyos aiws ext-upgrade def_abc --workspace ws_abc --dry-run", "buckyos aiws ext-upgrade def_abc,def_xyz --workspace ws_abc --migration ./migration.json"],
+  handler: async (ctx, input) => {
+    const pkg = inputString(input, "pkg_id");
+    const migration = inputString(input, "migration");
+    return aiws(ctx, "ext.upgrade", {
+      workspace_id: requiredInputString(input, "workspace_id"),
+      items: list(input, "defs").map((def_entity_id) => ({ def_entity_id, ...pkg ? { pkg_id: pkg } : {} })),
+      ...migration ? { migration: await migrationFile(ctx, migration) } : {},
+      ...input.force === true ? { force: true } : {},
+      ...input.dry_run === true ? { dry_run: true } : {},
+      ...ctx.idempotencyKey ? { idempotency_key: ctx.idempotencyKey } : {}
+    });
   }
 };
 const libraryCommand = {
   verb: "library",
-  summary: "Your AI Workspace control library: `list`, `install <file.pikg>` (an aiws package, dev mode), `remove <pkg_id>`",
-  positionals: [{ name: "action", description: "list | install | remove", required: true }, { name: "target", description: "install: local .pikg path; remove: package id", required: false }],
-  options: [],
-  inputSchema: { type: "object", properties: { action: { type: "string", enum: ["list", "install", "remove"] }, target: { type: "string" } }, required: ["action"], additionalProperties: false },
+  summary: "Your AI Workspace control library: `list` (each control with the identities it depends on, `deps`, and the package’s templates), `install <file.pikg>` (an aiws package, dev mode), `remove <pkg_id>`, `bundle <pkg_id> --out <file.json>` (the controls with their bytes, for `ext-import --bundle` in another Zone)",
+  positionals: [{ name: "action", description: "list | install | remove | bundle", required: true }, { name: "target", description: "install: local .pikg path; remove, bundle: package id", required: false }],
+  options: [
+    { name: "out", property: "out", description: "bundle: the JSON file to write", type: "string" },
+    { name: "idents", property: "idents", description: "bundle: only these controls (and what they build on), comma-separated identities", type: "string" }
+  ],
+  inputSchema: { type: "object", properties: { action: { type: "string", enum: ["list", "install", "remove", "bundle"] }, target: { type: "string" }, out: { type: "string" }, idents: { type: "string" } }, required: ["action"], additionalProperties: false },
   outputSchema: OBJECT_OUTPUT,
   resultSchemaVersion: 1,
   access: { mode: "fixed", level: "write" },
   asyncMode: "sync",
   requiresSession: true,
-  examples: ["buckyos aiws library list", "buckyos aiws library install ./kpi-pack-0.1.0.pikg", "buckyos aiws library remove kpi-pack.alice.bns.did"],
+  examples: ["buckyos aiws library list", "buckyos aiws library install ./kpi-pack-0.1.0.pikg", "buckyos aiws library remove kpi-pack.alice.bns.did", "buckyos aiws library bundle kpi-pack.alice.bns.did --out ./kpi-pack.bundle.json"],
   handler: async (ctx, input) => {
     const action = requiredInputString(input, "action");
     if (action === "list")
       return aiws(ctx, "ext.list_library", {});
     if (action === "remove")
       return aiws(ctx, "ext.uninstall", { pkg_id: requiredInputString(input, "target") });
+    if (action === "bundle") {
+      const host2 = getHost();
+      const out = host2.path.resolve(ctx.cwd, requiredInputString(input, "out"));
+      const idents = inputString(input, "idents");
+      const r = await aiws(ctx, "ext.library_bundle", { pkg_id: requiredInputString(input, "target"), ...idents ? { idents: list(input, "idents") } : {} });
+      const controls = Array.isArray(r.controls) ? r.controls : [];
+      await host2.writeTextFile(out, `${JSON.stringify({ pkg_id: r.pkg_id, controls }, null, 2)}
+`);
+      return { ok: true, out, pkg_id: r.pkg_id, controls: controls.map((c) => ({ ident: c.ident, version: c.version, digest: c.digest, deps: c.deps })) };
+    }
     if (action !== "install")
-      throw new UsageError("AIWS_USAGE", "library: list, install <file.pikg> or remove <pkg_id>");
+      throw new UsageError("AIWS_USAGE", "library: list, install <file.pikg>, remove <pkg_id> or bundle <pkg_id> --out <file.json>");
     const path = getHost().path.resolve(ctx.cwd, requiredInputString(input, "target"));
     return aiws(ctx, "ext.install", { pikg: await uploadPackage(ctx, path), mode: "dev" });
   }
 };
+async function relayBundle(ctx, ws, controls, opts) {
+  const pending = [...controls];
+  const needed = new Set(controls.flatMap((c) => c.deps ?? []));
+  const out = [];
+  while (pending.length > 0) {
+    const left = new Set(pending.map((c2) => c2.ident));
+    const c = pending.splice(Math.max(0, pending.findIndex((p) => (p.deps ?? []).every((d) => !left.has(d) || d === p.ident))), 1)[0];
+    try {
+      const r = await aiws(ctx, "ext.build", {
+        workspace_id: ws,
+        files: await sourceErrors(() => packBuildFiles(c.files.map((f) => ({ name: f.name, bytes: fromBase64(f.base64) })), sourceUploader(ctx))),
+        provenance: c.provenance,
+        ...opts.folderId ? { folder_id: opts.folderId } : {},
+        ...opts.upgrade ? { upgrade: true } : {},
+        ...opts.migration?.[c.ident] ? { migration: { [c.ident]: opts.migration[c.ident] } } : {}
+      });
+      out.push({ ident: c.ident, def_entity_id: r.def_entity_id, action: r.action ?? r.status, version: r.version });
+    } catch (error) {
+      if (opts.upgrade || !needed.has(c.ident) || !(error instanceof ToolError) || error.details.sub_code !== "EXT_IDENT_EXISTS")
+        throw error;
+      out.push({ ident: c.ident, def_entity_id: error.details.data?.def_entity_id, action: "satisfied" });
+    }
+  }
+  return out;
+}
 const extImportCommand = {
   verb: "ext-import",
-  summary: "Bring controls of your library into a Workspace (one Commit): <pkg_id>#<ident>, comma-separated",
-  positionals: [{ name: "items", description: "<pkg_id>#<author_did>#<name>[,…] (ext.list_library names them)", required: true }],
-  options: [WORKSPACE_OPTION, { name: "folder", property: "folder_id", description: "Data folder for the definitions (default: data/extensions)", type: "string" }],
-  inputSchema: workspaceInput({ items: { type: "string", minLength: 1 }, folder_id: { type: "string" } }, ["items"]),
+  summary: "Bring controls of your library into a Workspace (one Commit): <pkg_id>#<ident>, comma-separated; what they build on (deps) comes along, dependencies first, and an identity the Workspace already has satisfies it. --bundle builds a library bundle of another Zone instead",
+  description: 'Across Zones: `aiws library bundle <pkg_id> --out <file>` in the Zone of the library, then `aiws ext-import --bundle <file> --workspace <ws>` in the Zone of the Workspace: each control is built with its package provenance, dependencies first; a dependency the Workspace already holds is met by that definition. --upgrade (with --bundle) upgrades the identities the Workspace holds from another version, --migration naming a JSON file { "<author_did>#<name>": Migration } for a version that narrows what instances rely on. Upgrades from your library in the same Zone are `aiws ext-upgrade`.',
+  positionals: [{ name: "items", description: "<pkg_id>#<author_did>#<name>[,…] (ext.list_library names them); not with --bundle", required: false }],
+  options: [
+    WORKSPACE_OPTION,
+    { name: "folder", property: "folder_id", description: "Data folder for the definitions (default: data/extensions)", type: "string" },
+    { name: "bundle", property: "bundle", description: "A library bundle file (`aiws library bundle`, any Zone) to build instead of items", type: "string" },
+    { name: "upgrade", property: "upgrade", description: "With --bundle: upgrade identities the Workspace holds from another version", type: "boolean" },
+    { name: "migration", property: "migration", description: 'With --upgrade: JSON file { "<author_did>#<name>": Migration }', type: "string" }
+  ],
+  inputSchema: workspaceInput({ items: { type: "string", minLength: 1 }, folder_id: { type: "string" }, bundle: { type: "string" }, upgrade: { type: "boolean" }, migration: { type: "string" } }),
   outputSchema: OBJECT_OUTPUT,
   resultSchemaVersion: 1,
   access: { mode: "fixed", level: "write" },
   asyncMode: "sync",
   requiresSession: true,
-  examples: ["buckyos aiws ext-import kpi-pack.alice.bns.did#did:bns:alice#kpi-card --workspace ws_abc"],
-  handler: (ctx, input) => {
-    const items = list(input, "items").map((item) => {
-      const cut = item.indexOf("#");
-      if (cut <= 0)
-        throw new UsageError("AIWS_USAGE", `${item}: <pkg_id>#<ident>`);
-      return { pkg_id: item.slice(0, cut), ident: item.slice(cut + 1) };
-    });
+  examples: ["buckyos aiws ext-import kpi-pack.alice.bns.did#did:bns:alice#kpi-card --workspace ws_abc", "buckyos aiws ext-import --bundle ./kpi-pack.bundle.json --workspace ws_abc --upgrade"],
+  handler: async (ctx, input) => {
+    const ws = requiredInputString(input, "workspace_id");
     const folder = inputString(input, "folder_id");
-    return aiws(ctx, "ext.import", { workspace_id: requiredInputString(input, "workspace_id"), items, ...folder ? { folder_id: folder } : {} });
+    const bundle = inputString(input, "bundle");
+    const migration = inputString(input, "migration");
+    if (migration && input.upgrade !== true)
+      throw new UsageError("AIWS_USAGE", "--migration goes with --upgrade");
+    if (!bundle) {
+      if (input.upgrade === true)
+        throw new UsageError("AIWS_USAGE", "--upgrade goes with --bundle (a library bundle of another Zone); upgrade what came from your own library with `aiws ext-upgrade`");
+      const items = list(input, "items").map((item) => {
+        const cut = item.indexOf("#");
+        if (cut <= 0)
+          throw new UsageError("AIWS_USAGE", `${item}: <pkg_id>#<ident>`);
+        return { pkg_id: item.slice(0, cut), ident: item.slice(cut + 1) };
+      });
+      return aiws(ctx, "ext.import", { workspace_id: ws, items, ...folder ? { folder_id: folder } : {} });
+    }
+    if (inputString(input, "items"))
+      throw new UsageError("AIWS_USAGE", "pass items or --bundle, not both");
+    const host2 = getHost();
+    const file = JSON.parse(await host2.readTextFile(host2.path.resolve(ctx.cwd, bundle)));
+    if (!Array.isArray(file.controls) || file.controls.some((c) => !c || typeof c.ident !== "string" || !Array.isArray(c.files))) {
+      throw new UsageError("AIWS_USAGE", `--bundle ${bundle}: not a library bundle ({ pkg_id, controls: [{ ident, provenance, files }] }, from \`aiws library bundle\`)`);
+    }
+    const controls = await relayBundle(ctx, ws, file.controls, { folderId: folder, upgrade: input.upgrade === true, ...migration ? { migration: await migrationFile(ctx, migration) } : {} });
+    return { ok: true, controls };
+  }
+};
+function createParams(text2, declared) {
+  const out = {};
+  for (const pair of text2.split(",").map((s) => s.trim()).filter(Boolean)) {
+    const cut = pair.indexOf("=");
+    const name = cut > 0 ? pair.slice(0, cut) : "";
+    if (!Object.hasOwn(declared, name))
+      throw new UsageError("AIWS_USAGE", `--param ${pair}: the template's params are ${Object.keys(declared).join(", ") || "(none)"}`);
+    out[name] = typedValue(declared[name].type, pair.slice(cut + 1), `--param ${pair}`);
+  }
+  return out;
+}
+function exportParams(text2) {
+  const out = {};
+  for (const item of text2.split(",").map((s) => s.trim()).filter(Boolean)) {
+    const [name, type, ...rest] = item.split(":");
+    if (!name || !["string", "number", "boolean"].includes(type))
+      throw new UsageError("AIWS_USAGE", `--param ${item}: <name>:<string | number | boolean>[:<default>]`);
+    out[name] = { type, ...rest.length > 0 ? { default: typedValue(type, rest.join(":"), `--param ${item}`) } : {} };
+  }
+  return out;
+}
+function typedValue(type, raw, label) {
+  if (type === "number") {
+    const n = Number(raw);
+    if (!raw.trim() || !Number.isFinite(n))
+      throw new UsageError("AIWS_USAGE", `${label}: a number`);
+    return n;
+  }
+  if (type === "boolean") {
+    if (raw !== "true" && raw !== "false")
+      throw new UsageError("AIWS_USAGE", `${label}: true or false`);
+    return raw === "true";
+  }
+  return raw;
+}
+async function exportTemplate(ctx, input) {
+  const ws = requiredInputString(input, "workspace_id");
+  const id = requiredInputString(input, "id");
+  if (!/^[a-z0-9][a-z0-9-]{0,63}$/.test(id))
+    throw new UsageError("AIWS_USAGE", `--id ${id}: [a-z0-9][a-z0-9-]{0,63}`);
+  const description = inputString(input, "description");
+  const param = inputString(input, "param");
+  const template = {
+    id,
+    title: requiredInputString(input, "title"),
+    ...description ? { description } : {},
+    ...param ? { params: exportParams(param) } : {},
+    ...inputString(input, "reset") ? { reset: { tables: list(input, "reset") } } : {}
+  };
+  const out = getHost().path.resolve(ctx.cwd, requiredInputString(input, "out"));
+  const r = await aiws(ctx, "ext.export_template", { workspace_id: ws, surfaces: list(input, "surfaces"), ...inputString(input, "data") ? { data: list(input, "data") } : {}, template });
+  const item = expectObject$4(r.template, "ext.export_template.template");
+  const defs = (Array.isArray(r.controls) ? r.controls : []).map((c) => typeof c === "string" ? c : String(expectObject$4(c, "ext.export_template.controls[]").entity_id));
+  const files = /* @__PURE__ */ new Map();
+  let manifest = { manifest_version: AIWS_MANIFEST_VERSION, purpose: "aiws", host_api: {}, controls: [] };
+  if (defs.length > 0) {
+    const bundle = await exportBundle(extRpc(ctx), ws, defs, assetFetcher(ctx));
+    for (const [path, bytes] of bundle.files)
+      files.set(path, bytes);
+    manifest = bundle.manifest;
+  }
+  const dir = templateDir(id);
+  for (const f of Array.isArray(r.files) ? r.files : []) {
+    const path = f.path.startsWith(dir) ? f.path : `${dir}${f.path}`;
+    if (!isSourcePath(path))
+      throw new ToolError("INVALID_SERVICE_RESPONSE", `ext.export_template: ${f.path} is not a file of the template`);
+    files.set(path, fromBase64(f.base64));
+  }
+  manifest = { ...manifest, manifest_version: AIWS_MANIFEST_VERSION, workspace_templates: [item] };
+  files.set(AIWS_MANIFEST_FILE, new TextEncoder().encode(`${JSON.stringify(manifest, null, 2)}
+`));
+  const result = {
+    ok: true,
+    bundle: await writeBundle(out, files),
+    template: { id: item.id, title: item.title, digest: item.digest, requires: item.requires },
+    controls: controlSummary(manifest.controls)
+  };
+  return packBundle(ctx, input, out, id, result);
+}
+const templateCommand = {
+  verb: "template",
+  summary: "Workspace templates (snapshots carried in control packages): `list` (the templates of your library), `create <pkg_id>#<template_id>` (a new Workspace from one: answers its workspace_id), `export` (Surfaces of a Workspace as a template bundle; --pikg / --install pack it with the controls it needs and install it)",
+  description: "create: --title names the new Workspace; --param k=v[,k=v…] sets the template’s params (typed as the template declares them; `template list` shows them). Installing a template never creates a Workspace; each create makes an independent one. export: --workspace, --surfaces s1,s2, --id and --title are required; --data e1,e2 carries data entities along, --param name:type[:default][,…] (type string | number | boolean) declares what a creator fills into {{params.<name>}}, --reset t1,t2 names tables a new Workspace starts without rows. It writes <out>/aiws/ (aiws-manifest.json at manifest_version 3 with the template in workspace_templates, controls/<dir>/ of the controls it needs, templates/<id>/), then packs and installs it as `ext-export` does.",
+  positionals: [{ name: "action", description: "list | create | export", required: true }, { name: "target", description: "create: <pkg_id>#<template_id>", required: false }],
+  options: [
+    { name: "workspace", property: "workspace_id", description: "export: Workspace id (ws_…)", type: "string" },
+    { name: "surfaces", property: "surfaces", description: "export: Surface ids, comma-separated", type: "string" },
+    { name: "id", property: "id", description: "export: template id ([a-z0-9][a-z0-9-]{0,63})", type: "string" },
+    { name: "title", property: "title", description: "create: title of the new Workspace; export: title of the template", type: "string" },
+    { name: "description", property: "description", description: "export: what the template is for", type: "string" },
+    { name: "data", property: "data", description: "export: data entity ids to carry along, comma-separated", type: "string" },
+    { name: "param", property: "param", description: "create: k=v[,k=v…]; export: name:type[:default][,…]", type: "string" },
+    { name: "reset", property: "reset", description: "export: tables a new Workspace starts without rows, comma-separated", type: "string" },
+    { name: "out", property: "out", description: "export: local folder to write into (created)", type: "string" },
+    ...packageOptions("the template id")
+  ],
+  inputSchema: {
+    type: "object",
+    properties: {
+      action: { type: "string", enum: ["list", "create", "export"] },
+      target: { type: "string" },
+      workspace_id: { type: "string" },
+      surfaces: { type: "string" },
+      id: { type: "string" },
+      title: { type: "string" },
+      description: { type: "string" },
+      data: { type: "string" },
+      param: { type: "string" },
+      reset: { type: "string" },
+      out: { type: "string" },
+      ...PACKAGE_INPUT
+    },
+    required: ["action"],
+    additionalProperties: false
+  },
+  outputSchema: OBJECT_OUTPUT,
+  resultSchemaVersion: 1,
+  access: { mode: "fixed", level: "write" },
+  asyncMode: "sync",
+  requiresSession: true,
+  examples: [
+    "buckyos aiws template list",
+    'buckyos aiws template create team-pack.alice.bns.did#team-board --title "Ops board" --param team_name=Ops',
+    'buckyos aiws template export --workspace ws_abc --surfaces sf_board --id team-board --title "Team task board" --param team_name:string:Team --reset tasks --out ./team-pack --install'
+  ],
+  handler: async (ctx, input) => {
+    const action = requiredInputString(input, "action");
+    if (action === "list") {
+      const library = await aiws(ctx, "ext.list_library", {});
+      const packages = Array.isArray(library.packages) ? library.packages : [];
+      return { ok: true, templates: packages.flatMap((p) => (p.templates ?? []).map((t) => ({ ref: `${p.pkg_id}#${t.id}`, pkg_id: p.pkg_id, version: p.version, ...t }))) };
+    }
+    if (action === "export")
+      return exportTemplate(ctx, input);
+    if (action !== "create")
+      throw new UsageError("AIWS_USAGE", "template: list, create <pkg_id>#<template_id> or export --workspace <ws> --surfaces <ids> --id <id> --title <title> --out <dir>");
+    const target = requiredInputString(input, "target");
+    const cut = target.indexOf("#");
+    if (cut <= 0 || cut === target.length - 1)
+      throw new UsageError("AIWS_USAGE", `${target}: <pkg_id>#<template_id>`);
+    const [pkg_id, template_id] = [target.slice(0, cut), target.slice(cut + 1)];
+    const param = inputString(input, "param");
+    let params;
+    if (param) {
+      const library = await aiws(ctx, "ext.list_library", {});
+      const packages = Array.isArray(library.packages) ? library.packages : [];
+      const found = packages.find((p) => p.pkg_id === pkg_id)?.templates?.find((t) => t.id === template_id);
+      if (!found)
+        throw new UsageError("AIWS_USAGE", `${target} is not a template of your library (aiws template list)`);
+      params = createParams(param, found.params ?? {});
+    }
+    const title = inputString(input, "title");
+    return aiws(ctx, "ext.create_from_template", { pkg_id, template_id, ...title ? { title } : {}, ...params ? { params } : {} });
   }
 };
 function createAiwsModule() {
   return {
     name: "aiws",
-    summary: "AI Workspace: read a workspace, Block-controls (catalogue, import, export), extension controls (build, pull, export, library, import), and execute wish runs as their executor (claim, heartbeat, report)",
-    commands: [infoCommand, readCommand, queryCommand, controlsCommand, importCommand, exportCommand, buildCommand, pullCommand, extExportCommand, libraryCommand, extImportCommand, runGetCommand, runClaimCommand, runHeartbeatCommand, runFilesCommand, runToolCommand, runProgramCommand, runReportCommand]
+    summary: "AI Workspace: read a workspace, Block-controls (catalogue, import, export), extension controls (build, pull, export, library, import, upgrade), Workspace templates (list, create, export), and execute wish runs as their executor (claim, heartbeat, report)",
+    commands: [infoCommand, readCommand, queryCommand, controlsCommand, importCommand, exportCommand, buildCommand, pullCommand, extExportCommand, libraryCommand, extImportCommand, extUpgradeCommand, templateCommand, runGetCommand, runClaimCommand, runHeartbeatCommand, runFilesCommand, runToolCommand, runProgramCommand, runReportCommand]
   };
 }
 const VERSION = TOOL_VERSION;