buckyos 0.7.159 → 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, taskMgrTaskEventPath, ndm_proxy, objectUrl as objectUrl$1, ExecutorCommandStream } 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";
@@ -866,8 +866,8 @@ async function resolveConfig(explicit, environment2 = readEnvironment(), options
   const timeoutMs = explicit.timeout ? parseDuration(explicit.timeout) : DEFAULT_TIMEOUT_MS;
   if (endpoint)
     validateEndpoint(endpoint);
-  const sessionToken = explicit.sessionToken ?? environment2.BUCKYOS_APPCLIENT_SESSION_TOKEN;
-  if (sessionToken)
+  const sessionToken2 = explicit.sessionToken ?? environment2.BUCKYOS_APPCLIENT_SESSION_TOKEN;
+  if (sessionToken2)
     sources.session_token = explicit.sessionToken ? "argument" : "environment";
   if (profileName) {
     sources.profile = explicit.profile ? "argument" : environment2.BUCKYOS_TOOL_PROFILE ? "environment" : "config";
@@ -880,7 +880,7 @@ async function resolveConfig(explicit, environment2 = readEnvironment(), options
       zone,
       endpoint,
       identity,
-      sessionToken,
+      sessionToken: sessionToken2,
       sessionTokenFile: explicit.sessionTokenFile,
       output,
       defaultProtocol,
@@ -4164,6 +4164,7 @@ function derivedSelector(key) {
     agent: {},
     agent_skills: {},
     agent_tools: {},
+    aiws: {},
     script: {}
   };
   return selectors[key];
@@ -4482,6 +4483,28 @@ function validateServiceConfigTips(value, label) {
 function appDocObjectId(value) {
   return ndn.buildNamedObjectByJson("appdoc", value)[0].toString();
 }
+const AIWS_SUB_PACKAGE = "aiws";
+const MAX_AIWS_PAYLOAD_BYTES = 256 * 1024 * 1024;
+async function verifyAiwsPayload(tarGz) {
+  const files = /* @__PURE__ */ new Map();
+  for (const entry of await readTarGz(tarGz, MAX_AIWS_PAYLOAD_BYTES))
+    files.set(entry.path, entry.bytes);
+  let checked;
+  try {
+    checked = await verifyBundle(files);
+  } catch (error) {
+    throw invalid("aiws", `aiws bundle: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  const errors = checked.diagnostics.filter((d) => d.severity === "error");
+  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 })),
+    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();
   for (const entryValue of Object.values(packageMeta.content_index)) {
@@ -4490,7 +4513,12 @@ async function validateSnapshot(distDir, appDoc, packageMeta) {
     const digest = await digestFile(path);
     payloads.set(entry.path, digest);
   }
-  return validateObjectGraph(appDoc, packageMeta, payloads, true, false, true);
+  const validated = validateObjectGraph(appDoc, packageMeta, payloads, true, false, true);
+  if (appDoc.app_type === "aiws") {
+    for (const sub of validated.subpackages)
+      await verifyAiwsPayload(await getHost().readFile(join$1(distDir, sub.payload_path)));
+  }
+  return validated;
 }
 async function packSnapshot(distDir, destination, appDoc, packageMeta) {
   const validated = await validateSnapshot(distDir, appDoc, packageMeta);
@@ -4595,9 +4623,15 @@ async function inspectPikg(path) {
     Boolean(jwtEntry),
     !jsonDoc || !jwtDoc || appDocObjectId(jsonDoc) === appDocObjectId(jwtDoc)
   );
+  let aiws2;
+  if (appDoc.app_type === "aiws") {
+    const sub = validated.subpackages[0];
+    aiws2 = await verifyAiwsPayload(await readZipEntry(archive, archive.byName.get(sub.payload_path), MAX_AIWS_PAYLOAD_BYTES));
+  }
   const pikgDigest = await digestFile(path);
   return {
     schema_version: 1,
+    ...aiws2 ? { aiws: aiws2 } : {},
     protocol: PACKAGE_META_SCHEMA,
     pikg_path: resolve$2(path),
     size: pikgDigest.size,
@@ -4894,7 +4928,7 @@ function validateAppDocShape(appDoc) {
   }
   if (appDoc.doc_type !== "app")
     throw invalid("appdoc", "APPDOC.doc_type must be app");
-  if (!["service", "dapp", "web", "agent", "agent_skills"].includes(String(appDoc.app_type))) {
+  if (!["service", "dapp", "web", "agent", "agent_skills", "aiws"].includes(String(appDoc.app_type))) {
     throw invalid("appdoc", "APPDOC.app_type is invalid");
   }
   if (appDoc.name !== void 0)
@@ -4952,6 +4986,9 @@ function validateAppDocShape(appDoc) {
       throw invalid("appdoc", "an agent_skills App must contain only the agent_skills sub package");
     }
   }
+  if (appDoc.app_type === "aiws" && Object.keys(pkgList).join() !== AIWS_SUB_PACKAGE) {
+    throw invalid("appdoc", "an aiws package must contain only the aiws sub package");
+  }
   deriveNamespaceForPackage(appDoc);
 }
 function deriveNamespaceForPackage(appDoc) {
@@ -5205,7 +5242,7 @@ function validateContentHandlers(value, permissions) {
   }
   return value;
 }
-const PACKAGE_VERSION = "0.7.159";
+const PACKAGE_VERSION = "0.7.162";
 const TOOL_VERSION = PACKAGE_VERSION;
 const SDK_VERSION = PACKAGE_VERSION;
 const PROTOCOL_VERSION = "1";
@@ -5223,11 +5260,13 @@ const SHA256_ID = /^sha256:[0-9a-f]{64}$/;
 const OBJECT_ID = /^(?:appdoc|pkg):[0-9a-f]{64}$/;
 const SAFE_GENERATED_FILE = /^[A-Za-z0-9._-]+$/;
 const OBJECT_OUTPUT$c = { type: "object", additionalProperties: true };
-const APP_KINDS = ["static-web", "script", "docker", "agent-skills"];
+const APP_KINDS = ["static-web", "script", "docker", "agent-skills", "aiws-controls"];
 const PATH_KINDS = {
   "static-web": { key: "web", category: "web", selectorType: "static" },
   script: { key: "script", category: "dapp", selectorType: "single" },
-  "agent-skills": { key: "agent_skills", category: "agent_skills", selectorType: "single" }
+  "agent-skills": { key: "agent_skills", category: "agent_skills", selectorType: "single" },
+  // AI Workspace controls: one bundle (aiws-manifest.json + controls/<dir>/), installed into the AI Workspace library
+  "aiws-controls": { key: "aiws", category: "aiws", selectorType: "single" }
 };
 function packageEnvironmentQualifier(key, selector) {
   const effective = selector ?? derivedSelector(key);
@@ -5297,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",
@@ -5308,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
         },
@@ -5322,7 +5367,9 @@ function createPikgModule(dependencies = {}) {
         examples: [
           "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: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 --composite"
         ],
         handler: async (ctx, input) => await initCommand(ctx, input, docker)
       },
@@ -5345,7 +5392,7 @@ function createPikgModule(dependencies = {}) {
         execution: "local",
         networkAccess: false,
         examples: ["buckyos pikg build ./dapp_meta"],
-        handler: async (ctx, input) => await buildCommand(ctx, input, docker, now)
+        handler: async (ctx, input) => await buildCommand$1(ctx, input, docker, now)
       },
       {
         verb: "pack",
@@ -5562,11 +5609,15 @@ async function initCommand(ctx, input, docker) {
     try {
       await getHost().lstat(absoluteSource);
     } catch (error) {
-      if (isHostError(error, "NotFound")) {
+      if (!isHostError(error, "NotFound"))
+        throw error;
+      if (kind === "aiws-controls") {
+        await writeAiwsSkeleton(absoluteSource, owner, name, input.composite === true);
+        sourceSummary2.skeleton = true;
+      } else {
         await ctx.io.stderr(`warning: source does not exist yet: ${sourceSummary2.path}
 `);
-      } else
-        throw error;
+      }
     }
   }
   const appMeta = {
@@ -5626,7 +5677,26 @@ async function initCommand(ctx, input, docker) {
     next_command: `buckyos pikg build ${metaDir}`
   };
 }
-async function buildCommand(ctx, input, docker, now) {
+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 });
+  for (const [file, text2] of Object.entries(files))
+    await host2.writeTextFile(join(dir, "controls", name, file), text2);
+  const digest = await aiwsContentDigest(Object.entries(files).map(([file, text2]) => [file, encoder.encode(text2)]));
+  const manifest = {
+    manifest_version: AIWS_MANIFEST_VERSION,
+    purpose: "aiws",
+    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)}
+`);
+}
+async function buildCommand$1(ctx, input, docker, now) {
   const metaInput = optionalInputString(input, "meta_dir") ?? "./dapp_meta";
   const metaDir = await realDirectory(resolveFromCwd$1(ctx, metaInput), "dapp_meta");
   const appMeta = parseAppMeta(await readJson(join(metaDir, "app.json"), "app.json"));
@@ -11098,7 +11168,12 @@ async function aiws(ctx, method, params) {
     const error = expectObject$4(result.error, `${method}.error`);
     const code = typeof error.code === "string" ? error.code : "AIWS_ERROR";
     const detail = typeof error.detail === "string" ? error.detail : code;
-    throw new ToolError(code, `${code}${typeof error.sub_code === "string" ? `/${error.sub_code}` : ""}: ${detail}`);
+    const details = {};
+    if (typeof error.sub_code === "string")
+      details.sub_code = error.sub_code;
+    if (error.data !== void 0)
+      details.data = error.data;
+    throw new ToolError(code, `${code}${typeof error.sub_code === "string" ? `/${error.sub_code}` : ""}: ${detail}`, void 0, false, details);
   }
   return result;
 }
@@ -11471,11 +11546,630 @@ const exportCommand = {
     return { ok: true, format: result.format, kind: result.kind, path: out };
   }
 };
+async function sessionToken(ctx) {
+  const session = ctx.session;
+  if (!session)
+    throw new ToolError("AUTH_REQUIRED", "authenticated session is required", EXIT_AUTH);
+  return (await session.ensureValid()).token;
+}
+async function openHome(ctx) {
+  const session = ctx.session;
+  if (!session)
+    throw new ToolError("AUTH_REQUIRED", "authenticated session is required", EXIT_AUTH);
+  const nfsp = new NfspClient({ baseUrl: gatewayOrigin$2(ctx.connection.endpoint), sessionToken: async () => (await session.ensureValid()).token });
+  await nfsp.hello(["cli"]);
+  return nfsp;
+}
+function extRpc(ctx) {
+  return {
+    extBuild: (workspace_id, params) => aiws(ctx, "ext.build", { workspace_id, ...params }),
+    extExport: (workspace_id, entity_ids, purpose = "package") => aiws(ctx, "ext.export", { workspace_id, entity_ids, purpose })
+  };
+}
+function assetFetcher(ctx) {
+  return async (workspaceId, objId) => {
+    const response = await fetch(`${gatewayOrigin$2(ctx.connection.endpoint)}/kapi/aiworkspace/asset/${encodeURIComponent(workspaceId)}/${encodeURIComponent(objId)}`, {
+      headers: { Authorization: `Bearer ${await sessionToken(ctx)}` },
+      signal: ctx.signal
+    });
+    if (!response.ok)
+      throw new ToolError("AIWS_ASSET_UNAVAILABLE", `asset ${objId}: HTTP ${response.status}`);
+    return new Uint8Array(await response.arrayBuffer());
+  };
+}
+async function sourceErrors(run) {
+  try {
+    return await run();
+  } catch (error) {
+    if (error instanceof AiwsSourceError)
+      throw new ToolError("BUILD_FAILED", `BUILD_FAILED: ${error.message}`, void 0, false, { data: { diagnostics: error.diagnostics } });
+    throw error;
+  }
+}
+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 {
+    return (await getHost().stat(path)).isDirectory;
+  } catch {
+    return false;
+  }
+}
+async function localFiles(dir) {
+  const host2 = getHost();
+  const files = [];
+  const problems = [];
+  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" });
+    }
+  };
+  await walk(dir, "", 0);
+  if (files.length === 0)
+    problems.push({ file: "", severity: "error", message: `${dir} holds no files` });
+  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 < 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 {
+    return JSON.parse(await getHost().readTextFile(getHost().path.join(dir, LOCAL_STATE)));
+  } catch {
+    return null;
+  }
+}
+async function buildLocal(ctx, ws, dir, opts) {
+  const state = await localState(dir);
+  const result = await aiws(ctx, "ext.build", {
+    workspace_id: ws,
+    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.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)}
+`);
+  }
+  return result;
+}
+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, 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,
+    { name: "folder", property: "folder_id", description: "Data folder for the definition (default: data/extensions)", type: "string" },
+    { 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: "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" }, migration: { type: "string" } }, ["dir"]),
+  outputSchema: OBJECT_OUTPUT,
+  resultSchemaVersion: 1,
+  access: { mode: "fixed", level: "write" },
+  asyncMode: "sync",
+  requiresSession: true,
+  examples: ['buckyos aiws build "/home/alice/AI Workspace/Demo/controls/kpi-card" --workspace ws_abc', 'buckyos aiws build "/home/alice/AI Workspace/Demo/controls/kpi-card" --workspace ws_abc --watch'],
+  handler: async (ctx, input) => {
+    const ws = requiredInputString(input, "workspace_id");
+    const dir = requiredInputString(input, "dir");
+    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)
+        throw new UsageError("AIWS_USAGE", "--watch follows a Zone folder; rebuild a local folder yourself");
+      return buildLocal(ctx, ws, local, opts);
+    }
+    const nfsp = await openHome(ctx);
+    if (input.watch !== true)
+      return sourceErrors(() => buildControl(extRpc(ctx), nfsp, ws, dir, opts));
+    let builds = 0;
+    let failures = 0;
+    await watchControl(nfsp, dir, async () => {
+      try {
+        const r = await sourceErrors(() => buildControl(extRpc(ctx), nfsp, ws, dir, opts));
+        builds++;
+        await ctx.io.stderr(`built ${r.ident} v${r.version ?? "?"} (${r.unchanged ? "unchanged" : r.status})
+`);
+      } catch (error) {
+        failures++;
+        const diagnostics = error instanceof ToolError ? error.details.data?.diagnostics : void 0;
+        await ctx.io.stderr(`build failed: ${error instanceof Error ? error.message : String(error)}
+${diagnostics ? `${JSON.stringify(diagnostics, null, 2)}
+` : ""}`);
+      }
+    }, { signal: ctx.signal });
+    return { ok: true, watched: dir, builds, failures };
+  }
+};
+const pullCommand = {
+  verb: "pull",
+  summary: "Write a control definition’s Workspace snapshot into a folder — a Zone path (default) or a local one (--local) — as the base of the next build",
+  positionals: [{ name: "def", description: "Definition (buckyos.block-def) id", required: true }],
+  options: [WORKSPACE_OPTION, { name: "out", property: "out", description: "Folder to write (created)", type: "string", required: true }, { name: "local", property: "local", description: "Write into a local folder instead of the Zone", type: "boolean" }],
+  inputSchema: workspaceInput({ def: { type: "string", minLength: 1 }, out: { type: "string", minLength: 1 }, local: { type: "boolean" } }, ["def", "out"]),
+  outputSchema: OBJECT_OUTPUT,
+  resultSchemaVersion: 1,
+  access: { mode: "fixed", level: "write" },
+  asyncMode: "sync",
+  requiresSession: true,
+  examples: ['buckyos aiws pull def_abc --workspace ws_abc --out "/home/alice/AI Workspace/Demo/controls/kpi-card"'],
+  handler: async (ctx, input) => {
+    if (input.local === true) {
+      const ws = requiredInputString(input, "workspace_id");
+      const host2 = getHost();
+      const out = host2.path.resolve(ctx.cwd, requiredInputString(input, "out"));
+      const r2 = await aiws(ctx, "ext.export", { workspace_id: ws, entity_ids: [requiredInputString(input, "def")], purpose: "pull" });
+      const control = expectObject$4(r2.controls[0], "ext.export.controls[0]");
+      await host2.mkdir(out, { recursive: true });
+      const fetchAsset = assetFetcher(ctx);
+      const files = [];
+      for (const f of control.files) {
+        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
+          await host2.writeFile(target, await fetchAsset(ws, String(f.obj_id)));
+        files.push(f.name);
+      }
+      await host2.writeTextFile(host2.path.join(out, LOCAL_STATE), `${JSON.stringify({ workspace_id: ws, def_entity_id: control.entity_id, def_rev: control.def_rev, dir_rev: control.dir_rev, ident: control.ident, at: (/* @__PURE__ */ new Date()).toISOString() }, null, 2)}
+`);
+      return { ok: true, out, files };
+    }
+    const nfsp = await openHome(ctx);
+    const r = await pullControl(extRpc(ctx), nfsp, requiredInputString(input, "workspace_id"), requiredInputString(input, "def"), requiredInputString(input, "out"), assetFetcher(ctx));
+    return { ok: true, out: requiredInputString(input, "out"), ...r };
+  }
+};
+async function pikgVerb(ctx, verb, input) {
+  const command = createPikgModule().commands.find((c) => c.verb === verb);
+  if (!command)
+    throw new ToolError("INTERNAL", `pikg ${verb} is missing`);
+  return expectObject$4(await command.handler(ctx, input), `pikg ${verb}`);
+}
+async function uploadPackage(ctx, path) {
+  const bucket_id = `user/aiworkspace/${ctx.principal.id}/exports`;
+  const key = `aiws/${Date.now()}-${getHost().path.basename(path)}`;
+  const bytes = await getHost().readFile(path);
+  if (bytes.byteLength > 32 * 1024 * 1024)
+    throw new UsageError("FILE_TOO_LARGE", "a control package installed from the CLI is limited to 32 MiB");
+  const url = `${gatewayOrigin$2(ctx.connection.endpoint)}/bucket/v1/${bucket_id}/${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 ${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",
+  description: "Writes <out>/aiws/ (aiws-manifest.json + controls/<dir>/). --pikg (or --install) also runs pikg init/build/pack in <out> (kind aiws-controls); --install binds the .pikg into your aiworkspace exports bucket and calls ext.install.",
+  positionals: [{ name: "defs", description: "Definition (or instance) ids, comma-separated", required: true }],
+  options: [
+    WORKSPACE_OPTION,
+    { name: "out", property: "out", description: "Local folder to write into (created)", type: "string", required: true },
+    ...packageOptions("the first control’s")
+  ],
+  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" },
+  asyncMode: "sync",
+  requiresSession: true,
+  examples: ["buckyos aiws ext-export def_abc,def_xyz --workspace ws_abc --out ./kpi-pack --install"],
+  handler: async (ctx, input) => {
+    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` (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", "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>, 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; 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", "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");
+    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), and execute wish runs as their executor (claim, heartbeat, report)",
-    commands: [infoCommand, readCommand, queryCommand, controlsCommand, importCommand, exportCommand, 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;