buckyos 0.7.159 → 0.7.160

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 } 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,24 @@ 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 })) };
+}
 async function validateSnapshot(distDir, appDoc, packageMeta) {
   const payloads = /* @__PURE__ */ new Map();
   for (const entryValue of Object.values(packageMeta.content_index)) {
@@ -4490,7 +4509,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 +4619,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 +4924,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 +4982,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 +5238,7 @@ function validateContentHandlers(value, permissions) {
   }
   return value;
 }
-const PACKAGE_VERSION = "0.7.159";
+const PACKAGE_VERSION = "0.7.160";
 const TOOL_VERSION = PACKAGE_VERSION;
 const SDK_VERSION = PACKAGE_VERSION;
 const PROTOCOL_VERSION = "1";
@@ -5223,11 +5256,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);
@@ -5322,7 +5357,8 @@ 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"
         ],
         handler: async (ctx, input) => await initCommand(ctx, input, docker)
       },
@@ -5345,7 +5381,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 +5598,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);
+        sourceSummary2.skeleton = true;
+      } else {
         await ctx.io.stderr(`warning: source does not exist yet: ${sourceSummary2.path}
 `);
-      } else
-        throw error;
+      }
     }
   }
   const appMeta = {
@@ -5626,7 +5666,25 @@ 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) {
+  const files = controlSkeleton({ authorDid: ownerDid, name, title: name });
+  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: { declarative: 1 },
+    controls: [{ ident: `${ownerDid}#${name}`, name, kind: "declarative", 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 +11156,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 +11534,326 @@ 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 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 = [];
+  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 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("")) });
+  }
+  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));
+}
+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 localFiles(dir),
+    ...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 } : {}
+  });
+  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, ≤ 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.",
+  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" }
+  ],
+  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"]),
+  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 opts = { folderId: inputString(input, "folder_id"), force: input.force === true, dryRun: input.dry_run === true };
+    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);
+        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 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 },
+    { 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" }
+  ],
+  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"]),
+  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 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 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 },
+  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"],
+  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 !== "install")
+      throw new UsageError("AIWS_USAGE", "library: list, install <file.pikg> or remove <pkg_id>");
+    const path = getHost().path.resolve(ctx.cwd, requiredInputString(input, "target"));
+    return aiws(ctx, "ext.install", { pikg: await uploadPackage(ctx, path), mode: "dev" });
+  }
+};
+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"]),
+  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) };
+    });
+    const folder = inputString(input, "folder_id");
+    return aiws(ctx, "ext.import", { workspace_id: requiredInputString(input, "workspace_id"), items, ...folder ? { folder_id: folder } : {} });
+  }
+};
 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), 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]
   };
 }
 const VERSION = TOOL_VERSION;