@openbkn/bkn-sdk 0.1.1 → 0.1.3-rc.1

package/dist/cli.js

@@ -8,6 +8,7 @@ import {
   activePlatform,
   attachToken,
   changePasswordSafe,
+  classifyPath,
   createClient,
   credentialDeviceLogin,
   currentToken,
@@ -16,9 +17,11 @@ import {
   deletePlatform,
   deviceLogin,
   exportCreds,
+  filesUnder,
   formatError,
   getUserSafe,
   isHeadless,
+  lifecycleHint,
   listPlatforms,
   logout,
   openBrowser,
@@ -26,16 +29,19 @@ import {
   parsePkMap,
   rawCall,
   readPlatformConfig,
+  releaseLifecycleSessions,
   renderReportMarkdown,
+  renderTree,
   resolveContext,
   setActivePlatform,
   status,
   switchUser,
   toExitCode,
   use,
+  validateFixturePath,
   whoami,
   writePlatformConfig
-} from "./chunk-NC6DZ2AU.js";
+} from "./chunk-PC2F54XD.js";
 
 // src/cli.ts
 import { Command as Command17 } from "commander";
@@ -43,12 +49,12 @@ import { Command as Command17 } from "commander";
 // package.json
 var package_default = {
   name: "@openbkn/bkn-sdk",
-  version: "0.1.1",
+  version: "0.1.3-rc.1",
   description: "Unified TypeScript SDK + CLI for the BKN (Business Knowledge Network) platform.",
   type: "module",
   license: "Apache-2.0",
   engines: {
-    node: ">=18"
+    node: ">=22.19.0"
   },
   bin: {
     openbkn: "./dist/cli.js"
@@ -78,6 +84,7 @@ var package_default = {
     lint: "npm run check:deps && biome check . && tsc --noEmit",
     format: "biome format --write .",
     test: "vitest run",
+    "test:e2e:trace-business": "npm run build && node test/e2e/bkn-trace-business-interaction.mjs",
     "test:cover": "vitest run --coverage",
     ci: "npm run lint && npm test",
     prepublishOnly: "npm run ci && npm run build"
@@ -87,9 +94,9 @@ var package_default = {
     chalk: "^5.4.1",
     commander: "^13.1.0",
     "csv-parse": "^6.2.1",
-    "js-yaml": "^4.2.0",
+    "js-yaml": "^4.3.0",
     jszip: "^3.10.1",
-    undici: "^8.7.0",
+    undici: "^8.9.0",
     zod: "^3.24.1"
   },
   devDependencies: {
@@ -174,10 +181,15 @@ function renderOrgTree(nodes, prefix = "") {
 // src/utils/output.ts
 function printJson(value, opts = {}) {
   if (opts.json || opts.compact) {
-    process.stdout.write(`${JSON.stringify(value, null, opts.compact ? 0 : 2)}
+    const json = JSON.stringify(value === void 0 ? null : value, null, opts.compact ? 0 : 2);
+    process.stdout.write(`${json}
 `);
     return;
   }
+  if (value === void 0) {
+    process.stdout.write("(ok)\n");
+    return;
+  }
   const rows = toRows(value);
   if (rows) {
     const fullColumns = columnsOf(rows).filter((c) => rows.some((r) => stringifyCell(r[c]) !== ""));
@@ -248,8 +260,7 @@ var NOISE_COLS = /* @__PURE__ */ new Set([
   "status_message",
   "last_check_time",
   "last_discover_status",
-  "health_check_result",
-  "health_check_enabled"
+  "health_check_result"
 ]);
 var isNoiseCol = (c) => NOISE_COLS.has(c) || /_time$/.test(c);
 var isKeyCol = (c) => /^(id|name|key|title|label)$/i.test(c) || /_(id|name|key)$/i.test(c) || /^(status|state|type|category|mode|enabled|version|branch)$/i.test(c);
@@ -322,14 +333,25 @@ function promptLine(query, hidden = false) {
 
 // src/commands/_shared.ts
 import { readFileSync } from "fs";
+function traceOptionsFrom(o) {
+  const conversationId = (typeof o.conversationId === "string" ? o.conversationId : void 0) ?? process.env.BKN_CONVERSATION_ID;
+  const interactionId = (typeof o.interactionId === "string" ? o.interactionId : void 0) ?? process.env.BKN_INTERACTION_ID;
+  if (!conversationId && !interactionId) return void 0;
+  return {
+    ...conversationId ? { conversationId } : {},
+    ...interactionId ? { interactionId } : {}
+  };
+}
 function clientFrom(cmd) {
   const o = cmd.optsWithGlobals();
+  const trace = traceOptionsFrom(o);
   return createClient({
     baseUrl: o.baseUrl,
     token: o.token,
     user: o.user,
     businessDomain: o.bizDomain,
-    insecure: o.insecure
+    insecure: o.insecure,
+    ...trace ? { trace } : {}
   });
 }
 function outputOptions(cmd) {
@@ -1349,9 +1371,6 @@ function bknCommand() {
       outputOptions(cmd)
     );
   });
-  objectType?.command("properties <kn-id> <ot-id>").description("Get an object type's calculated properties").action(async (knId, otId, _opts, cmd) => {
-    printJson(await clientFrom(cmd).kn.objectTypeProperties(knId, otId), outputOptions(cmd));
-  });
   bkn.command("create <name>").description("Create an (empty) knowledge network").option("--branch <b>", "branch", "main").action(async (name, opts, cmd) => {
     printJson(await clientFrom(cmd).kn.create({ name, branch: opts.branch }), outputOptions(cmd));
   });
@@ -1480,19 +1499,6 @@ function bknCommand() {
   sched.command("delete <kn-id> <schedule-ids>").description("Delete action schedule(s) (comma-joined ids)").action(async (knId, ids, _o, cmd) => {
     printJson(await clientFrom(cmd).kn.actionScheduleDelete(knId, ids), outputOptions(cmd));
   });
-  const job = bkn.command("job").description("Build jobs \u2014 list/get/tasks");
-  job.command("list <kn-id>").description("List jobs").action(async (knId, _o, cmd) => {
-    printJson(await clientFrom(cmd).kn.jobs(knId), outputOptions(cmd));
-  });
-  job.command("get <kn-id> <job-id>").description("Get a job").action(async (knId, jobId, _o, cmd) => {
-    printJson(await clientFrom(cmd).kn.job(knId, jobId), outputOptions(cmd));
-  });
-  job.command("tasks <kn-id> <job-id>").description("List a job's tasks").action(async (knId, jobId, _o, cmd) => {
-    printJson(await clientFrom(cmd).kn.jobTasks(knId, jobId), outputOptions(cmd));
-  });
-  job.command("delete <kn-id> <job-ids>").description("Delete job(s) (comma-joined ids)").action(async (knId, ids, _o, cmd) => {
-    printJson(await clientFrom(cmd).kn.jobDelete(knId, ids), outputOptions(cmd));
-  });
   bkn.command("push <directory>").description("Pack a BKN directory into a tar and import it as a knowledge network").option("--branch <name>", "target branch", "main").option("--build", "submit a Vega build task for each object type declaring a vector index").option(
     "--embedding-model <id>",
     "embedding model id for declared vector indexes (with --build)"
@@ -1584,12 +1590,14 @@ function callCommand() {
     []
   ).option("-v, --verbose", "print request line to stderr").action(async (url, opts, cmd2) => {
     const g = cmd2.optsWithGlobals();
+    const trace = traceOptionsFrom(g);
     const ctx = resolveContext({
       baseUrl: g.baseUrl,
       token: g.token,
       user: g.user,
       businessDomain: g.bizDomain,
-      insecure: g.insecure
+      insecure: g.insecure,
+      ...trace ? { trace } : {}
     });
     const res = await rawCall(ctx, url, {
       method: opts.request,
@@ -1606,7 +1614,11 @@ function callCommand() {
       process.stdout.write(res.body.endsWith("\n") ? res.body : `${res.body}
 `);
     }
-    if (res.status >= 400) process.exitCode = 1;
+    if (res.status >= 400) {
+      const hint = lifecycleHint(res.body);
+      if (hint) console.error(hint);
+      process.exitCode = 1;
+    }
   });
   return group(cmd, "AUTHENTICATION & CONFIG");
 }
@@ -1822,9 +1834,13 @@ function dataflowCommand() {
   cmd.command("list").description("List all dataflows").action(async (_opts, cmd2) => {
     printJson(await clientFrom(cmd2).dataflows.list(), outputOptions(cmd2));
   });
-  cmd.command("runs <dagId>").description("List run records for one dataflow").option("--since <date>", "filter runs since a date").action(async (dagId, opts, cmd2) => {
+  cmd.command("runs <dagId>").description("List run records for one dataflow").option("--since <date>", "filter runs since a date").option("--limit <n>", "page size (backend default 20)", int6).option("--page <n>", "page (0-based; backend default 0)", int6).action(async (dagId, opts, cmd2) => {
     printJson(
-      await clientFrom(cmd2).dataflows.runs(dagId, { since: opts.since }),
+      await clientFrom(cmd2).dataflows.runs(dagId, {
+        since: opts.since,
+        page: opts.page,
+        limit: opts.limit
+      }),
       outputOptions(cmd2)
     );
   });
@@ -1899,7 +1915,6 @@ var ROUTES = {
   }),
   "POST /api/bkn/instances": (c, _q, b) => c.kn.objectTypeQuery(str(b.knId), str(b.objectTypeId), b.body ?? {}),
   "POST /api/bkn/subgraph": (c, _q, b) => c.kn.subgraph(str(b.knId), b.body ?? b),
-  "POST /api/bkn/properties": (c, _q, b) => c.kn.objectTypeProperties(str(b.knId), str(b.objectTypeId)),
   "GET /api/vega/catalogs": (c) => c.vega.catalogs(),
   "GET /api/vega/catalog": (c, q) => c.vega.getCatalog(req(q, "catalogId")),
   "GET /api/vega/catalog-resources": (c, q) => c.vega.catalogResources(req(q, "catalogId"), q.get("category") ?? void 0),
@@ -2120,20 +2135,24 @@ function resourceCommand() {
     });
     printJson(data, outputOptions(cmd2));
   });
-  cmd.command("find").description("Search resources by name (fuzzy; --exact for strict)").requiredOption("--name <name>", "resource name to search").option("--exact", "exact name match").option("--catalog-id <id>", "limit to a catalog").option("--datasource-id <id>", "alias of --catalog-id").action(async (opts, cmd2) => {
+  cmd.command("find").description("Search resources by name (fuzzy; --exact for strict)").requiredOption("--name <name>", "resource name to search").option("--exact", "exact name match").option("--catalog-id <id>", "limit to a catalog").option("--datasource-id <id>", "alias of --catalog-id").option("--limit <n>", "rows to scan before filtering", int9, DEFAULT_LIST_LIMIT).action(async (opts, cmd2) => {
     const data = await clientFrom(cmd2).resource.find(opts.name, {
       exact: opts.exact,
-      datasourceId: opts.catalogId ?? opts.datasourceId
+      datasourceId: opts.catalogId ?? opts.datasourceId,
+      limit: opts.limit
     });
     printJson(data, outputOptions(cmd2));
   });
   cmd.command("get <id>").description("Get resource details").action(async (id, _opts, cmd2) => {
     printJson(await clientFrom(cmd2).resource.get(id), outputOptions(cmd2));
   });
-  cmd.command("query <id>").description("Fetch data rows from a resource").option("--limit <n>", "row limit", int9, DEFAULT_QUERY_LIMIT).option("--offset <n>", "row offset", int9, 0).option("--need-total", "include total count").action(async (id, opts, cmd2) => {
+  cmd.command("query <id>").description("Fetch data rows from a resource").option("--limit <n>", "row limit", int9, DEFAULT_QUERY_LIMIT).option("--offset <n>", "row offset", int9, 0).option("--paging-mode <mode>", "paging mode: single | cursor").option("--keep-alive-sec <s>", "cursor keep-alive in seconds (60\u20133600)", int9).option("--cursor <cursor>", "opaque cursor returned by the previous page").option("--need-total", "include total count").action(async (id, opts, cmd2) => {
     const data = await clientFrom(cmd2).resource.query(id, {
       limit: opts.limit,
       offset: opts.offset,
+      pagingMode: opts.pagingMode,
+      keepAliveSec: opts.keepAliveSec,
+      cursor: opts.cursor,
       needTotal: opts.needTotal
     });
     printJson(data, outputOptions(cmd2));
@@ -2147,6 +2166,29 @@ function resourceCommand() {
 // src/commands/skill.ts
 import { Command as Command13 } from "commander";
 var int10 = (v) => Number.parseInt(v, 10);
+var positiveInt = (flag) => (v) => {
+  if (!/^\d+$/.test(v)) {
+    throw new InputError(`${flag} must be a positive integer (got '${v}')`);
+  }
+  const n = Number.parseInt(v, 10);
+  if (!Number.isSafeInteger(n) || n <= 0) {
+    throw new InputError(`${flag} must be a positive integer (got '${v}')`);
+  }
+  return n;
+};
+var MOCKED_EXIT_CODE = 125;
+function sandboxExitCode(result) {
+  if (result?.mocked) return MOCKED_EXIT_CODE;
+  const code = result?.exit_code ?? 0;
+  if (!Number.isSafeInteger(code) || code < 0) return 1;
+  return code > 255 ? 1 : code;
+}
+var SKILL_SOURCES = ["custom", "internal"];
+function checkSource(source) {
+  if (source === void 0 || SKILL_SOURCES.includes(source)) return source;
+  throw new InputError(`--source must be one of: ${SKILL_SOURCES.join(" | ")} (got '${source}')`);
+}
+var draftOption = (c) => c.option("--draft", "read the draft (management) version instead of the published one");
 function skillCommand() {
   const cmd = new Command13("skill").description("Skill registry and market");
   const listOpts = (c) => c.option("--name <s>", "filter by name").option("--source <s>", "filter by source").option("--status <s>", "filter by status").option("--limit <n>", "page size", int10, DEFAULT_LIST_LIMIT).option("--page <n>", "page", int10, 1);
@@ -2185,11 +2227,97 @@ function skillCommand() {
   cmd.command("delete <skill-id>").description("Delete a skill").action(async (id, _opts, cmd2) => {
     printJson(await clientFrom(cmd2).skills.delete(id), outputOptions(cmd2));
   });
-  cmd.command("content <skill-id>").description("Read a skill's SKILL.md content index").action(async (id, _opts, cmd2) => {
-    printJson(await clientFrom(cmd2).skills.content(id), outputOptions(cmd2));
+  draftOption(cmd.command("content <skill-id>")).description("Read a skill's SKILL.md content index").option("--raw", "write SKILL.md's own text instead of the index JSON").action(async (id, opts, cmd2) => {
+    const skills = clientFrom(cmd2).skills;
+    if (opts.raw) {
+      process.stdout.write(await skills.contentRaw(id, { draft: opts.draft }));
+      return;
+    }
+    printJson(await skills.content(id, { draft: opts.draft }), outputOptions(cmd2));
+  });
+  draftOption(cmd.command("read-file <skill-id> <rel-path>")).description("Read a file inside a skill (progressive)").option("--raw", "write the file's own text instead of the response JSON").action(async (id, relPath, opts, cmd2) => {
+    const skills = clientFrom(cmd2).skills;
+    if (opts.raw) {
+      process.stdout.write(await skills.readFileRaw(id, relPath, { draft: opts.draft }));
+      return;
+    }
+    printJson(await skills.readFile(id, relPath, { draft: opts.draft }), outputOptions(cmd2));
+  });
+  draftOption(cmd.command("files <skill-id> [path]")).description("List a skill's files (one level; --tree for the whole hierarchy)").option("--tree", "render the full hierarchy instead of one level").action(async (id, path, opts, cmd2) => {
+    const skills = clientFrom(cmd2).skills;
+    const out = outputOptions(cmd2);
+    if (opts.tree) {
+      const all = await skills.fileManifest(id, { draft: opts.draft });
+      if (path !== void 0) {
+        const kind = classifyPath(all, path);
+        if (kind === "file")
+          throw new InputError(`'${path}' is a file \u2014 use \`skill read-file\`.`);
+        if (kind === "missing") throw new InputError(`'${path}' not found in skill ${id}.`);
+      }
+      const files = filesUnder(all, path);
+      const bytes = files.reduce((sum, f) => sum + (f.size ?? 0), 0);
+      if (out.json || out.compact) {
+        printJson(
+          {
+            skillId: id,
+            path: path ?? "",
+            files: files.map((f) => ({
+              relPath: f.rel_path,
+              fileType: f.file_type,
+              size: f.size,
+              mime: f.mime_type
+            })),
+            totalFiles: files.length,
+            totalSize: bytes
+          },
+          out
+        );
+        return;
+      }
+      process.stdout.write(`${renderTree(files)}
+
+${files.length} files, ${bytes} B
+`);
+      return;
+    }
+    const listing = await skills.files(id, path, { draft: opts.draft });
+    if (out.json || out.compact) {
+      printJson(listing, out);
+      return;
+    }
+    printJson(
+      listing.entries.map(
+        (e) => e.type === "dir" ? { name: `${e.name}/`, type: "dir", size: e.size, mime: "" } : { name: e.name, type: e.fileType ?? "file", size: e.size, mime: e.mime ?? "" }
+      ),
+      out
+    );
+    process.stdout.write(
+      `${listing.entries.length} entries here; ${listing.totalFiles} files, ${listing.totalSize} B below
+`
+    );
+  });
+  cmd.command("names <ids...>").description("Resolve skill ids to names (unknown ids are skipped)").action(async (ids, _opts, cmd2) => {
+    printJson(await clientFrom(cmd2).skills.names(ids), outputOptions(cmd2));
   });
-  cmd.command("read-file <skill-id> <rel-path>").description("Read a file inside a skill (progressive)").action(async (id, relPath, _opts, cmd2) => {
-    printJson(await clientFrom(cmd2).skills.readFile(id, relPath), outputOptions(cmd2));
+  cmd.command("execute <skill-id>").description("Run a skill in the platform sandbox").requiredOption("--entry <shell>", "shell command to run inside the skill's work dir").option(
+    "--timeout <seconds>",
+    "sandbox time limit (the sandbox's own limit when omitted)",
+    positiveInt("--timeout")
+  ).option("--raw", "write the run's stdout/stderr straight through").option("--exit-code", "exit with the sandbox's exit code").action(async (id, opts, cmd2) => {
+    const result = await clientFrom(cmd2).skills.execute(id, {
+      entryShell: opts.entry,
+      timeout: opts.timeout
+    });
+    if (result?.mocked) {
+      process.stderr.write("warning: sandbox reported mocked=true \u2014 the skill did not run\n");
+    }
+    if (opts.raw) {
+      if (result?.stdout) process.stdout.write(result.stdout);
+      if (result?.stderr) process.stderr.write(result.stderr);
+    } else {
+      printJson(result, outputOptions(cmd2));
+    }
+    if (opts.exitCode) process.exitCode = sandboxExitCode(result);
   });
   cmd.command("history <skill-id>").description("Show a skill's version history").action(async (id, _opts, cmd2) => {
     printJson(await clientFrom(cmd2).skills.history(id), outputOptions(cmd2));
@@ -2200,15 +2328,21 @@ function skillCommand() {
       outputOptions(cmd2)
     );
   });
-  cmd.command("register <directory>").description("Zip a local skill directory and register it").option("--source <s>", "source tag").option("--extend-info <json>", "extra metadata as JSON").action(async (dir, opts, cmd2) => {
+  cmd.command("register <directory>").description("Zip a local skill directory and register it").option("--source <s>", `source tag: ${SKILL_SOURCES.join(" | ")}`, "custom").option("--extend-info <json>", "extra metadata as JSON").action(async (dir, opts, cmd2) => {
     const extendInfo = opts.extendInfo ? JSON.parse(opts.extendInfo) : void 0;
     printJson(
-      await clientFrom(cmd2).skills.register(dir, { source: opts.source, extendInfo }),
+      await clientFrom(cmd2).skills.register(dir, {
+        source: checkSource(opts.source),
+        extendInfo
+      }),
       outputOptions(cmd2)
     );
   });
-  cmd.command("download <skill-id> [out-path]").description("Download a skill archive to a local .zip").action(async (skillId, outPath, _o, cmd2) => {
-    printJson(await clientFrom(cmd2).skills.download(skillId, outPath), outputOptions(cmd2));
+  draftOption(cmd.command("download <skill-id> [out-path]")).description("Download a skill archive to a local .zip").action(async (skillId, outPath, opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).skills.download(skillId, outPath, { draft: opts.draft }),
+      outputOptions(cmd2)
+    );
   });
   cmd.command("install <skill-id> [directory]").description("Download a skill archive and extract it locally").action(async (skillId, dir, _o, cmd2) => {
     printJson(await clientFrom(cmd2).skills.install(skillId, dir), outputOptions(cmd2));
@@ -2281,8 +2415,15 @@ function toolboxCommand() {
 }
 function toolCommand() {
   const cmd = new Command14("tool").description("Tools inside a toolbox");
-  cmd.command("list").description("List tools in a toolbox").requiredOption("--toolbox <box-id>", "toolbox id").action(async (opts, cmd2) => {
-    printJson(await clientFrom(cmd2).toolboxes.tools(opts.toolbox), outputOptions(cmd2));
+  cmd.command("list").description("List tools in a toolbox").requiredOption("--toolbox <box-id>", "toolbox id").option("--limit <n>", "page size (backend default 10, max 100)", int11).option("--page <n>", "page (1-based; backend default 1)", int11).option("--all", "return every tool, ignoring page size").action(async (opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).toolboxes.tools(opts.toolbox, {
+        page: opts.page,
+        pageSize: opts.limit,
+        all: opts.all
+      }),
+      outputOptions(cmd2)
+    );
   });
   cmd.command("enable <tool-ids...>").description("Enable one or more tools").requiredOption("--toolbox <box-id>", "toolbox id").action(async (toolIds, opts, cmd2) => {
     printJson(
@@ -2420,6 +2561,111 @@ function traceCommand() {
   const cmd = new Command15("trace").description(
     "BKN Trace \u2014 fetch spans, diagnose (symbolic + LLM rubric), scan, eval-set, schema validate"
   );
+  cmd.command("graph <trace-id>").description("Fetch normalized trace graph by trace id").action(async (traceId, _opts, cmd2) => {
+    printJson(await clientFrom(cmd2).trace.graph(traceId), outputOptions(cmd2));
+  });
+  const conversations = cmd.command("conversations").description("Manage Trace conversations");
+  conversations.command("list").description("List conversations in the authorized owner scope").option("--limit <n>", "page size, 1..100", (value) => Number.parseInt(value, 10)).action(async (opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).trace.lifecycle.listConversations({ limit: opts.limit }),
+      outputOptions(cmd2)
+    );
+  });
+  conversations.command("ensure-current <external-conversation-key>").description("Ensure the current Core-owned conversation generation").option("--one-shot", "create a one-shot conversation").option("--idempotency-key <key>", "stable idempotency key").action(async (externalConversationKey, opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).trace.lifecycle.ensureConversation({
+        external_conversation_key: externalConversationKey,
+        idempotency_key: opts.idempotencyKey,
+        one_shot: Boolean(opts.oneShot)
+      }),
+      outputOptions(cmd2)
+    );
+  });
+  conversations.command("create-new-generation <external-conversation-key>").description("Create the next Core-owned conversation generation").requiredOption("--idempotency-key <key>", "stable idempotency key").action(async (externalConversationKey, opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).trace.lifecycle.createNewConversationGeneration({
+        external_conversation_key: externalConversationKey,
+        idempotency_key: opts.idempotencyKey
+      }),
+      outputOptions(cmd2)
+    );
+  });
+  conversations.command("resume <conversation-id>").description("Resume an existing authorized conversation").action(async (conversationId, _opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).trace.lifecycle.resumeConversation({
+        conversation_id: conversationId
+      }),
+      outputOptions(cmd2)
+    );
+  });
+  conversations.command("get <conversation-id>").description("Get an authorized conversation").action(async (conversationId, _opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).trace.lifecycle.getConversation(conversationId),
+      outputOptions(cmd2)
+    );
+  });
+  conversations.command("close <conversation-id>").description("Close an active conversation").option("--idempotency-key <key>", "stable idempotency key").action(async (conversationId, opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).trace.lifecycle.closeConversation(conversationId, {
+        idempotency_key: opts.idempotencyKey
+      }),
+      outputOptions(cmd2)
+    );
+  });
+  const interactions = cmd.command("interactions").description("Inspect Trace interactions");
+  interactions.command("start <conversation-id>").description("Start one managed interaction").requiredOption("--idempotency-key <key>", "stable idempotency key").option("--agent-name <name>", "conversation-level Agent display name").option(
+    "--lease-seconds <n>",
+    "interaction lease duration",
+    (value) => Number.parseInt(value, 10)
+  ).action(async (conversationId, opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).trace.lifecycle.startInteraction(conversationId, {
+        idempotency_key: opts.idempotencyKey,
+        agent_name: opts.agentName,
+        lease_seconds: opts.leaseSeconds
+      }),
+      outputOptions(cmd2)
+    );
+  });
+  interactions.command("get <interaction-id>").description("Get an authorized interaction").action(async (interactionId, _opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).trace.lifecycle.getInteraction(interactionId),
+      outputOptions(cmd2)
+    );
+  });
+  for (const action of ["complete", "fail", "cancel", "handoff"]) {
+    interactions.command(`${action} <interaction-id>`).description(`${action} a managed interaction using a 3.0 completion manifest`).requiredOption("--body-file <path>", "read completion manifest JSON from a protected file").action(async (interactionId, opts, cmd2) => {
+      const input = readBody(opts);
+      const lifecycle = clientFrom(cmd2).trace.lifecycle;
+      const terminal = {
+        complete: lifecycle.completeInteraction,
+        fail: lifecycle.failInteraction,
+        cancel: lifecycle.cancelInteraction,
+        handoff: lifecycle.handoffInteraction
+      }[action];
+      printJson(await terminal(interactionId, input), outputOptions(cmd2));
+    });
+  }
+  const operations = cmd.command("operations").description("Inspect and retry operations");
+  operations.command("get <operation-id>").description("Get an authorized operation").action(async (operationId, _opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).trace.lifecycle.getOperation(operationId),
+      outputOptions(cmd2)
+    );
+  });
+  operations.command("retry <operation-id>").description("Create the next retry attempt for an eligible failed operation").requiredOption("--body-file <path>", "read retry request JSON from a protected file").action(async (operationId, opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).trace.lifecycle.retryOperationAttempt(
+        operationId,
+        readBody(opts)
+      ),
+      outputOptions(cmd2)
+    );
+  });
+  const receipts = cmd.command("receipts").description("Inspect durable operation receipts");
+  receipts.command("get <receipt-id>").description("Get an authorized operation receipt").action(async (receiptId, _opts, cmd2) => {
+    printJson(await clientFrom(cmd2).trace.lifecycle.getReceipt(receiptId), outputOptions(cmd2));
+  });
   cmd.command("get <conversation-id>").description("Fetch all trace spans for a conversation").option("--max-spans <n>", "max spans", (v) => Number.parseInt(v, 10)).action(async (conversationId, opts, cmd2) => {
     printJson(
       await clientFrom(cmd2).trace.spans(conversationId, { maxSpans: opts.maxSpans }),
@@ -2471,12 +2717,60 @@ function traceCommand() {
     printJson(result, outputOptions(cmd2));
     if (!result.valid) process.exitCode = 1;
   });
+  cmd.command("validate-fixture <path>").description("Validate BKN Trace 1.0/2.0/2.1 fixture JSON files").action(async (path, _opts, cmd2) => {
+    const result = validateFixturePath(path);
+    printJson(result, outputOptions(cmd2));
+    if (!result.ok) process.exitCode = 1;
+  });
   return group(cmd, "TRACE AI");
 }
 
 // src/commands/vega.ts
 import { Command as Command16 } from "commander";
 var int12 = (v) => Number.parseInt(v, 10);
+var bool = (value) => {
+  if (value === "true") return true;
+  if (value === "false") return false;
+  throw new InputError("boolean value must be true or false");
+};
+var parseJsonObject = (value, flag) => {
+  let parsed;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    throw new InputError(`${flag} must be valid JSON`);
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new InputError(`${flag} must be a JSON object`);
+  }
+  return parsed;
+};
+var parseStringRecord = (value, flag) => {
+  const parsed = parseJsonObject(value, flag);
+  if (Object.values(parsed).some((item) => typeof item !== "string")) {
+    throw new InputError(`${flag} values must be strings`);
+  }
+  return parsed;
+};
+var healthCheckSchedule = (mode, cronExpr) => {
+  if (!mode) {
+    if (cronExpr) throw new InputError("a health-check cron expression requires enabled mode");
+    return void 0;
+  }
+  if (mode === "enabled") {
+    if (!cronExpr) {
+      throw new InputError("a health-check cron expression is required in enabled mode");
+    }
+    return { mode, cronExpr };
+  }
+  if (mode === "inherit" || mode === "disabled") {
+    if (cronExpr) {
+      throw new InputError("a health-check cron expression is only valid in enabled mode");
+    }
+    return { mode };
+  }
+  throw new InputError("health-check mode must be inherit, enabled, or disabled");
+};
 var parsePairs2 = (raw) => {
   if (!raw) return void 0;
   return raw.split(",").map((part) => {
@@ -2511,48 +2805,54 @@ function vegaCommand() {
   catalog.command("get <id>").description("Get a catalog by id").action(async (id, _opts, cmd) => {
     printJson(await clientFrom(cmd).vega.getCatalog(id), outputOptions(cmd));
   });
-  catalog.command("resources <id>").description("List resources under a catalog").option("--category <c>", "filter by category (e.g. table)").action(async (id, opts, cmd) => {
-    printJson(await clientFrom(cmd).vega.catalogResources(id, opts.category), outputOptions(cmd));
+  catalog.command("resources <id>").description("List resources under a catalog").option("--category <c>", "filter by category (e.g. table)").option("--limit <n>", "page size (backend default 20, max 1000; -1 = all)", int12).option("--offset <n>", "page offset", int12, 0).action(async (id, opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).vega.catalogResources(id, opts.category, opts.limit, opts.offset),
+      outputOptions(cmd)
+    );
   });
-  catalog.command("health <ids...>").description("Health-status for one or more catalogs").action(async (ids, _opts, cmd) => {
-    printJson(await clientFrom(cmd).vega.catalogHealth(ids), outputOptions(cmd));
+  catalog.command("health <id>").description("Health-status for a catalog").action(async (id, _opts, cmd) => {
+    printJson(await clientFrom(cmd).vega.catalogHealth(id), outputOptions(cmd));
   });
-  catalog.command("create").description("Create a catalog (data source)").requiredOption("--name <s>", "catalog name").requiredOption("--connector-type <s>", "connector type (e.g. mysql)").requiredOption("--connector-config <json>", "connector config JSON").option("--id <id>", "explicit catalog id").option("--tags <t1,t2>", "comma-separated tags").option("--description <s>", "description").option("--enabled", "create enabled (default: disabled)").option("--internal", "create an internal catalog").option("--extensions <json>", "extension key/value JSON object").action(async (opts, cmd) => {
-    let connectorConfig;
-    try {
-      connectorConfig = JSON.parse(opts.connectorConfig);
-    } catch {
-      throw new Error("--connector-config must be valid JSON");
-    }
-    const extensions = opts.extensions ? JSON.parse(opts.extensions) : void 0;
+  catalog.command("create").description("Create a catalog (data source)").requiredOption("--name <s>", "catalog name").requiredOption("--connector-type <s>", "connector type (e.g. mysql)").requiredOption("--connector-config <json>", "connector config JSON").option("--id <id>", "explicit catalog id").option("--tags <t1,t2>", "comma-separated tags").option("--description <s>", "description").option("--enabled", "create enabled (default: disabled)").option("--internal", "create an internal catalog").option("--extensions <json>", "extension key/value JSON object").option("--allow-unhealthy", "save the catalog when its connection test fails").option("--health-check-mode <mode>", "health schedule: inherit | enabled | disabled").option("--health-check-cron <expr>", "cron expression for enabled health checks").action(async (opts, cmd) => {
+    const connectorConfig = parseJsonObject(opts.connectorConfig, "--connector-config");
+    const extensions = opts.extensions ? parseStringRecord(opts.extensions, "--extensions") : void 0;
     printJson(
-      await clientFrom(cmd).vega.createCatalog({
-        id: opts.id,
-        name: opts.name,
-        connectorType: opts.connectorType,
-        connectorConfig,
-        tags: opts.tags ? String(opts.tags).split(",").map((t) => t.trim()).filter(Boolean) : void 0,
-        description: opts.description,
-        enabled: opts.enabled ? true : void 0,
-        internal: opts.internal ? true : void 0,
-        extensions
-      }),
+      await clientFrom(cmd).vega.createCatalog(
+        {
+          id: opts.id,
+          name: opts.name,
+          connectorType: opts.connectorType,
+          connectorConfig,
+          tags: opts.tags ? String(opts.tags).split(",").map((t) => t.trim()).filter(Boolean) : void 0,
+          description: opts.description,
+          enabled: opts.enabled ? true : void 0,
+          internal: opts.internal ? true : void 0,
+          extensions,
+          healthCheckSchedule: healthCheckSchedule(opts.healthCheckMode, opts.healthCheckCron)
+        },
+        { allowUnhealthy: opts.allowUnhealthy ? true : void 0 }
+      ),
       outputOptions(cmd)
     );
   });
-  catalog.command("update <id>").description("Update a catalog").option("--name <s>", "catalog name").option("--connector-type <s>", "connector type").option("--connector-config <json>", "connector config JSON").option("--tags <t1,t2>", "comma-separated tags").option("--description <s>", "description").option("--enabled <bool>", "enabled state").option("--extensions <json>", "extension key/value JSON object").action(async (id, opts, cmd) => {
-    const connectorConfig = opts.connectorConfig ? JSON.parse(opts.connectorConfig) : void 0;
-    const extensions = opts.extensions ? JSON.parse(opts.extensions) : void 0;
+  catalog.command("update <id>").description("Fully update a catalog").requiredOption("--name <s>", "catalog name").requiredOption("--connector-type <s>", "connector type").requiredOption("--enabled <bool>", "current enabled state", bool).option("--connector-config <json>", "connector config JSON").option("--tags <t1,t2>", "comma-separated tags").option("--description <s>", "description").option("--extensions <json>", "extension key/value JSON object").option("--allow-unhealthy", "save the update when its connection test fails").action(async (id, opts, cmd) => {
+    const connectorConfig = opts.connectorConfig ? parseJsonObject(opts.connectorConfig, "--connector-config") : void 0;
+    const extensions = opts.extensions ? parseStringRecord(opts.extensions, "--extensions") : void 0;
     printJson(
-      await clientFrom(cmd).vega.updateCatalog(id, {
-        name: opts.name,
-        connectorType: opts.connectorType,
-        connectorConfig,
-        tags: opts.tags ? String(opts.tags).split(",").map((t) => t.trim()).filter(Boolean) : void 0,
-        description: opts.description,
-        enabled: opts.enabled === void 0 ? void 0 : opts.enabled === "true",
-        extensions
-      }),
+      await clientFrom(cmd).vega.updateCatalog(
+        id,
+        {
+          name: opts.name,
+          connectorType: opts.connectorType,
+          connectorConfig,
+          tags: opts.tags ? String(opts.tags).split(",").map((t) => t.trim()).filter(Boolean) : void 0,
+          description: opts.description,
+          enabled: opts.enabled,
+          extensions
+        },
+        { allowUnhealthy: opts.allowUnhealthy ? true : void 0 }
+      ),
       outputOptions(cmd)
     );
   });
@@ -2568,6 +2868,26 @@ function vegaCommand() {
   catalog.command("test-connection <id>").description("Test a catalog connection").action(async (id, _opts, cmd) => {
     printJson(await clientFrom(cmd).vega.testCatalogConnection(id), outputOptions(cmd));
   });
+  catalog.command("test-connection-config").description("Test an unpersisted catalog connection configuration").requiredOption("--connector-type <s>", "connector type").requiredOption("--connector-config <json>", "connector config JSON").action(async (opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).vega.testCatalogConnectionConfig({
+        connectorType: opts.connectorType,
+        connectorConfig: parseJsonObject(opts.connectorConfig, "--connector-config")
+      }),
+      outputOptions(cmd)
+    );
+  });
+  catalog.command("health-check-schedule <id>").description("Get a catalog health-check schedule").action(async (id, _opts, cmd) => {
+    printJson(await clientFrom(cmd).vega.catalogHealthCheckSchedule(id), outputOptions(cmd));
+  });
+  catalog.command("set-health-check-schedule <id>").description("Update a catalog health-check schedule").requiredOption("--mode <mode>", "health schedule: inherit | enabled | disabled").option("--cron <expr>", "cron expression for enabled health checks").action(async (id, opts, cmd) => {
+    const schedule = healthCheckSchedule(opts.mode, opts.cron);
+    if (!schedule) throw new InputError("--mode is required");
+    printJson(
+      await clientFrom(cmd).vega.updateCatalogHealthCheckSchedule(id, schedule),
+      outputOptions(cmd)
+    );
+  });
   catalog.command("discover <id>").description("Trigger catalog resource discovery").option("--wait", "wait for discovery to complete").action(async (id, opts, cmd) => {
     printJson(
       await clientFrom(cmd).vega.discoverCatalog(id, Boolean(opts.wait)),
@@ -2581,12 +2901,12 @@ function vegaCommand() {
   connector.command("get <type>").description("Get a connector type").action(async (type, _opts, cmd) => {
     printJson(await clientFrom(cmd).vega.connectorType(type), outputOptions(cmd));
   });
-  vega.command("sql").description("Run SQL / OpenSearch DSL directly against a vega-backend data source").requiredOption("--resource-type <type>", "source type (mysql | postgresql | opensearch | \u2026)").option("--query-type <type>", "query mode: standard | stream").option(
+  vega.command("sql").description("Run SQL / OpenSearch DSL directly against a vega-backend data source").option(
     "--query <sql>",
     "SQL string; reference a resource with a {{<resource-id>}} placeholder"
-  ).option("--stream-size <n>", "streaming batch size (100\u201310000)", int12).option("--query-timeout <s>", "query timeout in seconds (1\u20133600)", int12).option(
+  ).option("--input-dialect <dialect>", "SQL input dialect: postgres | mysql | trino | duckdb").option("--paging-mode <mode>", "paging mode: single | cursor").option("--limit <n>", "page size (cursor mode requires it)", int12).option("--offset <n>", "first-page offset", int12).option("--keep-alive-sec <s>", "cursor keep-alive in seconds (60\u20133600)", int12).option("--cursor <cursor>", "opaque cursor returned by the previous page").option("--need-total", "include the complete total count").option("--query-timeout-sec <s>", "query timeout in seconds (1\u20133600)", int12).option(
     "-d, --data <json>",
-    "full request body as JSON (advanced; wins over --query/--resource-type)"
+    "full request body as JSON (advanced; wins over individual query flags)"
   ).action(async (opts, cmd) => {
     let body;
     if (opts.data) {
@@ -2595,16 +2915,34 @@ function vegaCommand() {
       } catch {
         throw new InputError("--data must be valid JSON");
       }
+    } else if (opts.cursor) {
+      if (opts.query || opts.inputDialect || opts.pagingMode || opts.limit !== void 0 || opts.offset !== void 0 || opts.keepAliveSec !== void 0 || opts.queryTimeoutSec !== void 0) {
+        throw new InputError("--cursor cannot be combined with initial-query options");
+      }
+      body = {
+        paging: { cursor: opts.cursor },
+        ...opts.needTotal ? { need_total: true } : {}
+      };
     } else {
       if (!opts.query) {
-        throw new InputError("Provide --query (and optionally --resource-type), or --data.");
+        throw new InputError("Provide --query, --cursor, or --data.");
+      }
+      if (opts.pagingMode === "cursor" && opts.limit === void 0) {
+        throw new InputError("--limit is required when --paging-mode cursor");
       }
+      const paging = {
+        ...opts.pagingMode ? { mode: opts.pagingMode } : {},
+        ...opts.limit !== void 0 ? { limit: opts.limit } : {},
+        ...opts.offset !== void 0 ? { offset: opts.offset } : {},
+        ...opts.keepAliveSec !== void 0 ? { keep_alive_sec: opts.keepAliveSec } : {}
+      };
       body = {
         query: opts.query,
-        resource_type: opts.resourceType,
-        ...opts.queryType ? { query_type: opts.queryType } : {},
-        ...opts.streamSize !== void 0 ? { stream_size: opts.streamSize } : {},
-        ...opts.queryTimeout !== void 0 ? { query_timeout: opts.queryTimeout } : {}
+        query_format: "sql",
+        ...opts.inputDialect ? { input_dialect: opts.inputDialect } : {},
+        ...Object.keys(paging).length ? { paging } : {},
+        ...opts.needTotal ? { need_total: true } : {},
+        ...opts.queryTimeoutSec !== void 0 ? { query_timeout_sec: opts.queryTimeoutSec } : {}
       };
     }
     printJson(await clientFrom(cmd).vega.sql(body), outputOptions(cmd));
@@ -2665,11 +3003,16 @@ function vegaCommand() {
     );
     printJson(task, outputOptions(cmd));
   });
-  dataset.command("build-status <resource-id> <task-id>").description("Show a BuildTask's state and progress").action(async (_resourceId, taskId, _opts, cmd) => {
+  dataset.command("build-status <task-id>").description("Show a BuildTask's state and progress").action(async (taskId, _opts, cmd) => {
     const task = await clientFrom(cmd).vega.buildStatus(taskId);
     printJson(task, outputOptions(cmd));
   });
-  dataset.command("build-list").description("List BuildTasks").option("--limit <n>", "page size", int12, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int12, 0).option("--resource-id <id>", "filter by resource id").option("--catalog-id <id>", "filter by catalog id").option("--status <status>", "comma-separated statuses").option("--active", "only running/init tasks").option("--mode <mode>", "filter by mode: batch | streaming").option("--order-by <field>", "default | created_at | updated_at | status | mode").option("--order <dir>", "asc | desc").action(async (opts, cmd) => {
+  dataset.command("build-list").description("List BuildTasks").option("--limit <n>", "page size", int12, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int12, 0).option("--resource-id <id>", "filter by resource id").option("--catalog-id <id>", "filter by catalog id").option("--status <status>", "comma-separated statuses").option("--active", "only running/init tasks").option("--mode <mode>", "filter by mode: batch | streaming").option("--order-by <field>", "created_at | updated_at").option("--order <dir>", "asc | desc").action(async (opts, cmd) => {
+    if (opts.orderBy === "default") {
+      throw new InputError(
+        '--order-by default is no longer supported; use "created_at" or "updated_at"'
+      );
+    }
     printJson(
       await clientFrom(cmd).vega.buildTasks({
         limit: opts.limit,
@@ -2685,7 +3028,7 @@ function vegaCommand() {
       outputOptions(cmd)
     );
   });
-  dataset.command("build-start <task-id>").description("Start a BuildTask").option("--reset", "restart from the beginning").action(async (taskId, opts, cmd) => {
+  dataset.command("build-start <task-id>").description("Start a BuildTask").option("--reset", "restart a full task from the beginning (ignored for incremental tasks)").action(async (taskId, opts, cmd) => {
     printJson(
       await clientFrom(cmd).vega.startBuildTask(taskId, { reset: opts.reset }),
       outputOptions(cmd)
@@ -2708,7 +3051,7 @@ function vegaCommand() {
 
 // src/cli.ts
 var program = new Command17();
-program.name("openbkn").description("Operate the BKN platform from the CLI").version(package_default.version, "-V, --version", "output the version number").option("--base-url <url>", "platform base URL (env: BKN_BASE_URL)").option("--token <value>", "access token (env: BKN_TOKEN)").option("--user <id|name>", "use specific user credentials (env: BKN_USER)").option("--json", "machine-readable JSON output").option("--compact", "single-line JSON output").option("--full", "human view: show all columns (default trims to the key ones)").option("--biz-domain <s>", "business domain (alias: -bd)").option("-k, --insecure", "skip TLS verification (dev / self-signed only)").showHelpAfterError();
+program.name("openbkn").description("Operate the BKN platform from the CLI").version(package_default.version, "-V, --version", "output the version number").option("--base-url <url>", "platform base URL (env: BKN_BASE_URL)").option("--token <value>", "access token (env: BKN_TOKEN)").option("--user <id|name>", "use specific user credentials (env: BKN_USER)").option("--json", "machine-readable JSON output").option("--compact", "single-line JSON output").option("--full", "human view: show all columns (default trims to the key ones)").option("--biz-domain <s>", "business domain (alias: -bd)").option("--conversation-id <id>", "BKN Trace conversation id (env: BKN_CONVERSATION_ID)").option("--interaction-id <id>", "BKN Trace interaction id (env: BKN_INTERACTION_ID)").option("-k, --insecure", "skip TLS verification (dev / self-signed only)").showHelpAfterError();
 program.addCommand(authCommand());
 program.addCommand(callCommand());
 program.addCommand(configCommand());
@@ -2732,6 +3075,8 @@ try {
   await program.parseAsync(argv);
 } catch (err) {
   console.error(formatError(err));
+  await releaseLifecycleSessions();
   process.exit(toExitCode(err));
 }
+await releaseLifecycleSessions();
 //# sourceMappingURL=cli.js.map