@openbkn/bkn-sdk 0.1.2 → 0.1.3

package/dist/{chunk-LH3ONZGQ.js → chunk-PC2F54XD.js}

@@ -20,6 +20,14 @@ var HttpError = class extends Error {
     this.hint = hint;
   }
 };
+var ToolError = class extends Error {
+  code;
+  constructor(message, code) {
+    super(message);
+    this.name = "ToolError";
+    if (code) this.code = code;
+  }
+};
 var InputError = class extends Error {
   constructor(message) {
     super(message);
@@ -38,14 +46,15 @@ function formatError(err2) {
   if (err2 instanceof HttpError) {
     const serverMsg = serverError(err2.body);
     if (err2.status === 401) {
-      const next = err2.hint ?? "Run `openbkn auth login` and retry.";
-      return `Not authorized (HTTP 401)${serverMsg ? `: ${serverMsg}` : ""}. ${next}`;
+      const next2 = err2.hint ?? "Run `openbkn auth login` and retry.";
+      return `Not authorized (HTTP 401)${serverMsg ? `: ${serverMsg}` : ""}. ${next2}`;
     }
     if (err2.status === 403) {
       return `Forbidden (HTTP 403)${serverMsg ? `: ${serverMsg}` : " \u2014 admin privileges required"}.`;
     }
     const detail = err2.body ? `: ${truncate(err2.body, 500)}` : "";
-    return `Request failed (HTTP ${err2.status} ${err2.statusText})${detail}`;
+    const next = err2.hint ? ` ${err2.hint}` : "";
+    return `Request failed (HTTP ${err2.status} ${err2.statusText})${detail}${next}`;
   }
   if (err2 instanceof Error) {
     const cause = err2.cause;
@@ -81,10 +90,23 @@ import { spawn } from "child_process";
 
 // src/api/tls.ts
 import { Agent, FormData as UndiciFormData, fetch as undiciFetch } from "undici";
-var insecureAgent;
-function insecureDispatcher() {
-  insecureAgent ??= new Agent({ connect: { rejectUnauthorized: false } });
-  return insecureAgent;
+var UNDICI_HEADERS_TIMEOUT_MS = 3e5;
+var agents = /* @__PURE__ */ new Map();
+function dispatcherFor(insecure, headersTimeoutMs) {
+  const key = `${insecure}|${headersTimeoutMs ?? ""}`;
+  let agent = agents.get(key);
+  if (!agent) {
+    agent = new Agent({
+      ...insecure ? { connect: { rejectUnauthorized: false } } : {},
+      ...headersTimeoutMs === void 0 ? {} : (
+        // undici also enforces a body deadline; a request that waits this
+        // long for headers is not going to stream its body any faster.
+        { headersTimeout: headersTimeoutMs, bodyTimeout: headersTimeoutMs }
+      )
+    });
+    agents.set(key, agent);
+  }
+  return agent;
 }
 function isFormData(body) {
   return typeof body === "object" && body !== null && body[Symbol.toStringTag] === "FormData";
@@ -98,12 +120,13 @@ function toUndiciBody(body) {
   }
   return form2;
 }
-function tlsFetch(insecure, url, init) {
-  if (!insecure) return fetch(url, init);
+function tlsFetch(insecure, url, init, headersTimeoutMs) {
+  const needsAgent = headersTimeoutMs !== void 0 && headersTimeoutMs > UNDICI_HEADERS_TIMEOUT_MS;
+  if (!insecure && !needsAgent) return fetch(url, init);
   return undiciFetch(url, {
     ...init,
     ...init?.body === void 0 || init?.body === null ? {} : { body: toUndiciBody(init.body) },
-    dispatcher: insecureDispatcher()
+    dispatcher: dispatcherFor(insecure === true, needsAgent ? headersTimeoutMs : void 0)
   });
 }
 
@@ -426,33 +449,59 @@ async function request(ctx, path, init = {}) {
   const hasBody = init.body !== void 0;
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), init.timeoutMs ?? DEFAULT_TIMEOUT_MS);
-  const send = () => tlsFetch(ctx.insecure, url, {
-    method: init.method ?? (hasBody ? "POST" : "GET"),
-    headers: buildHeaders(ctx, {
-      ...hasBody ? { "content-type": "application/json" } : {},
-      ...init.headers
-    }),
-    body: hasBody ? JSON.stringify(init.body) : void 0,
-    redirect: init.redirect,
-    signal: controller.signal
-  });
+  const send = () => tlsFetch(
+    ctx.insecure,
+    url,
+    {
+      method: init.method ?? (hasBody ? "POST" : "GET"),
+      headers: buildHeaders(ctx, {
+        ...hasBody ? { "content-type": "application/json" } : {},
+        ...init.headers
+      }),
+      body: hasBody ? JSON.stringify(init.body) : void 0,
+      redirect: init.redirect,
+      signal: controller.signal
+    },
+    init.headersTimeoutMs
+  );
   try {
     let res = await send();
     if (res.status === 401 && ctx.refresh && await tryRefresh(ctx)) {
       res = await send();
     }
     const text = await res.text();
-    if (!res.ok) throw new HttpError(res.status, res.statusText, text, hintFor(ctx, res.status));
+    if (!res.ok) {
+      throw new HttpError(res.status, res.statusText, text, hintFor(ctx, res.status, text));
+    }
     return text ? JSON.parse(text) : void 0;
   } finally {
     clearTimeout(timer);
   }
 }
-function hintFor(ctx, status2) {
+function hintFor(ctx, status2, body) {
   if (status2 === 401 && ctx.token.startsWith("bak_")) {
     return "AppKey invalid / expired / revoked / owner disabled \u2014 re-issue with `openbkn appkey create` (or `appkey regenerate <id>`). Do not auto-retry.";
   }
-  return void 0;
+  return lifecycleHint(body);
+}
+var LIFECYCLE_ACTIONS = /* @__PURE__ */ new Set([
+  "create_conversation",
+  "start_interaction",
+  "ensure_operation",
+  "bkn_start_interaction"
+]);
+function lifecycleHint(body) {
+  if (!LIFECYCLE_ACTIONS.has(requiredAction(body) ?? "")) return void 0;
+  return "This deploy requires a managed lifecycle session: the request needs a `bkn_context` with conversation_id and interaction_id. Easiest fix: use the `openbkn bkn` / `openbkn context` commands, which open and release one for you. To do it by hand, check `openbkn context info` for the deploy's lifecycle tools \u2014 where it lists `bkn_create_conversation`, call that first and pass the conversation_id it returns to `bkn_start_interaction`; where it does not, `bkn_start_interaction` alone returns both ids. Either way: `openbkn context tool-call <kn-id> <tool> --args '{...}'`.";
+}
+function requiredAction(body) {
+  try {
+    const parsed = JSON.parse(body);
+    const action = parsed.error?.required_action;
+    return typeof action === "string" ? action : void 0;
+  } catch {
+    return void 0;
+  }
 }
 async function tryRefresh(ctx) {
   if (!ctx.refresh) return false;
@@ -1194,7 +1243,7 @@ function setSkillMembers(agent, members) {
   if (!config.skills || typeof config.skills !== "object") config.skills = {};
   config.skills.skills = members;
 }
-function agents(ctx) {
+function agents2(ctx) {
   return {
     list: (opts) => listAgents(ctx, opts),
     get: (agentId) => getAgent(ctx, agentId),
@@ -1243,6 +1292,9 @@ function agents(ctx) {
   };
 }
 
+// src/api/lifecycle.ts
+import { createHash, randomUUID as randomUUID2 } from "crypto";
+
 // src/api/context-loader.ts
 var MCP_PATH = "/api/agent-retrieval/v1/mcp";
 var PROTOCOL = "2024-11-05";
@@ -1280,18 +1332,25 @@ function parseBody(text) {
     throw new Error(`Context-loader returned invalid JSON: ${text.slice(0, 200)}`);
   }
 }
-async function post(ctx, knId, sessionId, body) {
-  const res = await authFetch(
-    ctx,
-    () => tlsFetch(ctx.insecure, mcpUrl(ctx), {
-      method: "POST",
-      headers: headers(ctx, knId, sessionId),
-      body: JSON.stringify(body)
-    })
-  );
-  const text = await res.text();
-  if (!res.ok) throw new HttpError(res.status, res.statusText, text);
-  return { res, text };
+async function post(ctx, knId, sessionId, body, timeoutMs) {
+  const controller = timeoutMs === void 0 ? void 0 : new AbortController();
+  const timer = controller === void 0 ? void 0 : setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await authFetch(
+      ctx,
+      () => tlsFetch(ctx.insecure, mcpUrl(ctx), {
+        method: "POST",
+        headers: headers(ctx, knId, sessionId),
+        body: JSON.stringify(body),
+        ...controller ? { signal: controller.signal } : {}
+      })
+    );
+    const text = await res.text();
+    if (!res.ok) throw new HttpError(res.status, res.statusText, text);
+    return { res, text };
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
 }
 async function ensureSession(ctx, knId) {
   const key = `${mcpUrl(ctx)}:${knId}`;
@@ -1314,31 +1373,103 @@ async function ensureSession(ctx, knId) {
   sessions.set(key, { id: sessionId, at: Date.now() });
   return sessionId;
 }
-function unwrap(parsed) {
+function toolErrorCode(structuredContent) {
+  const code = structuredContent?.error?.code;
+  return typeof code === "string" ? code : void 0;
+}
+function unwrapToolResult(parsed) {
   const rpc = parsed;
   if (rpc.error) throw new Error(`Context-loader error: ${rpc.error.message}`);
   const result = rpc.result;
-  if (result === void 0) return parsed;
+  if (result === void 0) return { value: parsed };
+  const structuredContent = result.structuredContent;
+  const receipt = structuredContent?.bkn_receipt;
   const content = result.content;
+  if (result.isError === true) {
+    const message = Array.isArray(content) && content[0] && typeof content[0].text === "string" ? content[0].text : "tool call failed";
+    throw new ToolError(`Context-loader error: ${message}`, toolErrorCode(structuredContent));
+  }
   if (Array.isArray(content) && content[0] && typeof content[0].text === "string") {
     try {
-      return JSON.parse(content[0].text);
+      return { value: JSON.parse(content[0].text), receipt };
     } catch {
-      return { raw: content[0].text };
+      if (structuredContent !== void 0) {
+        return { value: structuredContent, receipt };
+      }
+      return { value: { raw: content[0].text }, receipt };
     }
   }
-  return result;
+  return { value: result, receipt };
+}
+function toolCallParams(name, args, options) {
+  const meta = {
+    ...options?.hostConversationKey ? { "openbkn.ai/host-conversation-key": options.hostConversationKey } : {},
+    ...options?.clientInvocationId ? { "openbkn.ai/client-invocation-id": options.clientInvocationId } : {}
+  };
+  return {
+    name,
+    arguments: args,
+    ...Object.keys(meta).length > 0 ? { _meta: meta } : {}
+  };
+}
+async function callToolRaw(ctx, knId, name, args, options, timeoutMs) {
+  const operationCtx = operationContext(ctx);
+  const sessionId = await ensureSession(operationCtx, knId);
+  const { text } = await post(
+    operationCtx,
+    knId,
+    sessionId,
+    {
+      jsonrpc: "2.0",
+      method: "tools/call",
+      params: toolCallParams(name, args, options),
+      id: nextId()
+    },
+    timeoutMs
+  );
+  return unwrapToolResult(parseBody(text)).value;
+}
+var LIFECYCLE_TOOLS = /* @__PURE__ */ new Set([
+  "bkn_create_conversation",
+  "bkn_resume_conversation",
+  "bkn_start_interaction",
+  "bkn_complete_interaction",
+  "bkn_finish_interaction",
+  "bkn_fail_interaction",
+  "bkn_cancel_interaction",
+  "bkn_handoff_interaction",
+  "bkn_close_conversation",
+  "bkn_get_operation",
+  "bkn_retry_operation",
+  "bkn_get_receipt"
+]);
+function callTool(ctx, knId, name, args, options) {
+  if (LIFECYCLE_TOOLS.has(name)) return callToolRaw(ctx, knId, name, args, options);
+  if (args.bkn_context !== void 0) return callToolRaw(ctx, knId, name, args, options);
+  return withManagedLifecycle(
+    ctx,
+    knId,
+    questionFor(name, args),
+    (bknContext) => callToolRaw(ctx, knId, name, bknContext ? { ...args, bkn_context: bknContext } : args, options)
+  );
+}
+function questionFor(name, args) {
+  return typeof args.query === "string" && args.query ? args.query : name;
 }
-async function callTool(ctx, knId, name, args) {
+async function callManagedTool(ctx, knId, name, args, options) {
   const operationCtx = operationContext(ctx);
   const sessionId = await ensureSession(operationCtx, knId);
   const { text } = await post(operationCtx, knId, sessionId, {
     jsonrpc: "2.0",
     method: "tools/call",
-    params: { name, arguments: args },
+    params: toolCallParams(name, args, options),
     id: nextId()
   });
-  return unwrap(parseBody(text));
+  const result = unwrapToolResult(parseBody(text));
+  if (!result.receipt) {
+    throw new Error("Context-loader managed tool response did not include bkn_receipt");
+  }
+  return { value: result.value, receipt: result.receipt };
 }
 async function callMethod(ctx, knId, method, params = {}) {
   const operationCtx = operationContext(ctx);
@@ -1406,6 +1537,225 @@ function getPrompt(ctx, knId, name, args = {}) {
   return callMethod(ctx, knId, "prompts/get", { name, arguments: args });
 }
 
+// src/api/lifecycle.ts
+var V1_MARKER = "bkn_create_conversation";
+var V2_MARKER = "bkn_start_interaction";
+var STALE_SESSION_CODES = /* @__PURE__ */ new Set([
+  "conversation_required",
+  "interaction_required",
+  "interaction_terminal",
+  "interaction_in_progress",
+  "lease_expired",
+  "lease_invalid",
+  "lease_superseded"
+]);
+var PROCESS_ID = randomUUID2();
+var generation = 0;
+var AGENT_NAME = "openbkn-sdk";
+var RELEASE_TIMEOUT_MS = 3e3;
+var contracts = /* @__PURE__ */ new Map();
+var PROBE_FAILURE_TTL_MS = 3e4;
+var probeFailures = /* @__PURE__ */ new Map();
+var sessions2 = /* @__PURE__ */ new Map();
+function lifecycleContract(ctx) {
+  const failureKey = `${ctx.baseUrl}\0${identityOf(ctx)}`;
+  const failedAt = probeFailures.get(failureKey);
+  if (failedAt !== void 0) {
+    if (Date.now() - failedAt < PROBE_FAILURE_TTL_MS) return Promise.resolve("none");
+    probeFailures.delete(failureKey);
+  }
+  let pending = contracts.get(ctx.baseUrl);
+  if (!pending) {
+    pending = mcpInfo(ctx).then((info) => {
+      const names = toolNames(info);
+      if (names.includes(V1_MARKER)) return "managed-v1";
+      return names.includes(V2_MARKER) ? "managed-v2" : "none";
+    });
+    contracts.set(ctx.baseUrl, pending);
+    pending.catch((err2) => {
+      contracts.delete(ctx.baseUrl);
+      if (!isAuthFailure(err2)) probeFailures.set(failureKey, Date.now());
+    });
+  }
+  return pending.catch(() => "none");
+}
+function isAuthFailure(err2) {
+  return err2 instanceof HttpError && (err2.status === 401 || err2.status === 403);
+}
+function toolNames(info) {
+  const tools = info?.tools;
+  if (!Array.isArray(tools)) return [];
+  return tools.flatMap((tool) => typeof tool?.name === "string" ? [tool.name] : []);
+}
+function callerOwnedSession(ctx) {
+  const conversationId = ctx.trace?.conversationId;
+  const interactionId = ctx.trace?.interactionId;
+  return conversationId && interactionId ? { conversationId, interactionId } : void 0;
+}
+function readId(result, field, tool) {
+  const value = result?.[field];
+  if (typeof value !== "string" || !value) {
+    throw new Error(`Managed lifecycle: ${tool} returned no ${field}.`);
+  }
+  return value;
+}
+function callerNamedConversation(ctx) {
+  return ctx.trace?.interactionId ? void 0 : ctx.trace?.conversationId;
+}
+async function openSession(ctx, knId, contract, question) {
+  generation += 1;
+  const named = callerNamedConversation(ctx);
+  if (contract === "managed-v2") {
+    const started2 = await callToolRaw(ctx, knId, V2_MARKER, {
+      question,
+      // The name is fixed when the conversation is created, so it belongs only
+      // on the call that creates one. Joining a conversation the caller named
+      // and relabelling it `openbkn-sdk` would rewrite their attribution — the
+      // v1 join below has always omitted it, and this is the same decision.
+      ...named ? { conversation_id: named } : (
+        // Display-only, but the only thing separating a session the SDK
+        // opened from a real agent's in a Trace listing.
+        { agent_name: AGENT_NAME }
+      )
+    });
+    return {
+      contract,
+      ctx,
+      knId,
+      conversationId: readId(started2, "conversation_id", V2_MARKER),
+      interactionId: readId(started2, "interaction_id", V2_MARKER)
+    };
+  }
+  if (named) {
+    const started2 = await callToolRaw(ctx, knId, V2_MARKER, {
+      conversation_id: named,
+      idempotency_key: `start:${PROCESS_ID}:${generation}`,
+      question
+    });
+    return {
+      contract,
+      ctx,
+      knId,
+      conversationId: named,
+      interactionId: readId(started2, "interaction_id", V2_MARKER)
+    };
+  }
+  const conversation = await callToolRaw(ctx, knId, V1_MARKER, {
+    external_conversation_key: `cli:${PROCESS_ID}:${generation}`,
+    // Nothing closes this conversation: a CLI invocation has no answer to close
+    // over, and v1's closure manifest must enumerate every operation it
+    // produced. one_shot hands it to the server's idle sweeper instead.
+    one_shot: true
+  });
+  const conversationId = readId(conversation, "conversation_id", V1_MARKER);
+  const started = await callToolRaw(ctx, knId, V2_MARKER, {
+    conversation_id: conversationId,
+    idempotency_key: `start:${PROCESS_ID}:${generation}`,
+    question
+  });
+  return {
+    contract,
+    ctx,
+    knId,
+    conversationId,
+    interactionId: readId(started, "interaction_id", V2_MARKER)
+  };
+}
+function identityOf(ctx) {
+  return createHash("sha256").update(`${ctx.token}\0${ctx.businessDomain}`).digest("hex").slice(0, 16);
+}
+function sessionKey(ctx, knId) {
+  return `${ctx.baseUrl}\0${knId}\0${identityOf(ctx)}\0${ctx.trace?.conversationId ?? ""}`;
+}
+function ensureSession2(ctx, knId, contract, question) {
+  const key = sessionKey(ctx, knId);
+  const cached = sessions2.get(key);
+  if (cached) return cached;
+  const opening = openSession(ctx, knId, contract, question);
+  sessions2.set(key, opening);
+  opening.catch(() => sessions2.delete(key));
+  return opening;
+}
+function newOperationKey() {
+  return `op:${randomUUID2()}`;
+}
+function contextFor(session, contract) {
+  return {
+    conversation_id: session.conversationId,
+    interaction_id: session.interactionId,
+    // v2 validates bkn_context strictly and rejects the field.
+    ...contract === "managed-v1" ? { operation_key: newOperationKey() } : {}
+  };
+}
+async function bknContextFor(ctx, knId, question) {
+  const contract = await lifecycleContract(ctx);
+  if (contract === "none") return void 0;
+  const owned = callerOwnedSession(ctx);
+  if (owned) return contextFor(owned, contract);
+  try {
+    return contextFor(await ensureSession2(ctx, knId, contract, question), contract);
+  } catch {
+    return void 0;
+  }
+}
+function serverErrorCode(err2) {
+  if (err2 instanceof ToolError) return err2.code;
+  if (!(err2 instanceof HttpError)) return void 0;
+  try {
+    const parsed = JSON.parse(err2.body);
+    return typeof parsed.error?.code === "string" ? parsed.error.code : void 0;
+  } catch {
+    return void 0;
+  }
+}
+async function withManagedLifecycle(ctx, knId, question, send) {
+  const first = await bknContextFor(ctx, knId, question);
+  try {
+    return await send(first);
+  } catch (err2) {
+    const code = serverErrorCode(err2);
+    if (!first || callerOwnedSession(ctx) || !code || !STALE_SESSION_CODES.has(code)) throw err2;
+    sessions2.delete(sessionKey(ctx, knId));
+    const reopened = await bknContextFor(ctx, knId, question);
+    if (!reopened) throw err2;
+    return await send(reopened);
+  }
+}
+async function releaseLifecycleSessions() {
+  const pending = [...sessions2.values()];
+  sessions2.clear();
+  await Promise.all(pending.map((opening) => withDeadline(releaseOne(opening))));
+}
+function withDeadline(work) {
+  return new Promise((resolve7) => {
+    const timer = setTimeout(resolve7, RELEASE_TIMEOUT_MS);
+    timer.unref?.();
+    work.finally(() => {
+      clearTimeout(timer);
+      resolve7();
+    });
+  });
+}
+async function releaseOne(opening) {
+  try {
+    const session = await opening;
+    if (session.contract !== "managed-v2") return;
+    await callToolRaw(
+      session.ctx,
+      session.knId,
+      "bkn_finish_interaction",
+      {
+        interaction_id: session.interactionId,
+        outcome: "cancelled",
+        reason: "client session ended"
+      },
+      void 0,
+      RELEASE_TIMEOUT_MS
+    );
+  } catch {
+  }
+}
+
 // src/resources/context-loader.ts
 function context(ctx) {
   return {
@@ -1418,7 +1768,8 @@ function context(ctx) {
     relationTypes: (knId, ids) => getRelationTypes(ctx, knId, ids),
     info: () => mcpInfo(ctx),
     tools: (knId) => listTools(ctx, knId),
-    toolCall: (knId, name, args) => callTool(ctx, knId, name, args),
+    toolCall: (knId, name, args, options) => callTool(ctx, knId, name, args, options),
+    managedToolCall: (knId, name, args, options) => callManagedTool(ctx, knId, name, args, options),
     // Generic MCP method passthrough — covers methods not yet wrapped, so the
     // surface doesn't have to grow every time the server adds one.
     callMethod: (knId, method, params) => callMethod(ctx, knId, method, params),
@@ -1715,22 +2066,39 @@ function searchMetrics(ctx, knId, body) {
   });
 }
 function validateMetric(ctx, knId, body) {
-  return request(ctx, `${ONTOLOGY_BASE}/${encodeURIComponent(knId)}/metrics/validate`, {
+  return request(ctx, `${ONTOLOGY_BASE}/${encodeURIComponent(knId)}/metrics/validation`, {
     method: "POST",
     body
   });
 }
+function searchBody(knId, query, opts) {
+  return {
+    kn_id: knId,
+    query,
+    mode: opts.mode ?? "keyword_vector_retrieval",
+    max_concepts: opts.maxConcepts ?? 10,
+    return_query_understanding: opts.returnQueryUnderstanding ?? false
+  };
+}
 function semanticSearch(ctx, knId, query, opts = {}) {
-  return request(ctx, `${RETRIEVAL_BASE}/semantic-search`, {
-    method: "POST",
-    body: {
-      kn_id: knId,
-      query,
-      mode: opts.mode ?? "keyword_vector_retrieval",
-      max_concepts: opts.maxConcepts ?? 10,
-      return_query_understanding: opts.returnQueryUnderstanding ?? false
-    }
-  });
+  if (opts.bknContext) {
+    return request(ctx, `${RETRIEVAL_BASE}/semantic-search`, {
+      method: "POST",
+      body: { ...searchBody(knId, query, opts), bkn_context: opts.bknContext }
+    });
+  }
+  return withManagedLifecycle(
+    ctx,
+    knId,
+    query,
+    (bknContext) => request(ctx, `${RETRIEVAL_BASE}/semantic-search`, {
+      method: "POST",
+      body: {
+        ...searchBody(knId, query, opts),
+        ...bknContext ? { bkn_context: bknContext } : {}
+      }
+    })
+  );
 }
 
 // src/api/resources.ts
@@ -3194,28 +3562,102 @@ function deleteActionSchedules(ctx, knId, ids) {
 import { z } from "zod";
 var VEGA_BASE = "/api/vega-backend/v1";
 var BuildMode = z.enum(["batch", "streaming"]);
-var CreateBuildTaskRequest = z.object({
-  resource_id: z.string().min(1),
-  mode: BuildMode,
-  execute_type: z.enum(["incremental", "full"]).optional()
-});
+var BuildTaskExecuteType = z.enum(["incremental", "full"]);
+var BuildTaskStatus = z.enum([
+  "init",
+  "running",
+  "stopping",
+  "stopped",
+  "completed",
+  "failed"
+]);
+var CatalogHealthCheckScheduleMode = z.enum(["inherit", "enabled", "disabled"]);
+var CatalogHealthCheckStatus = z.enum([
+  "healthy",
+  "degraded",
+  "unhealthy",
+  "offline",
+  "unchecked"
+]);
+var CatalogHealthStatus = z.object({
+  id: z.string(),
+  health_check_status: CatalogHealthCheckStatus,
+  last_check_time: z.number().optional(),
+  health_check_result: z.string().optional()
+}).passthrough();
+var CatalogHealthCheckSchedule = z.object({
+  catalog_id: z.string(),
+  mode: CatalogHealthCheckScheduleMode,
+  cron_expr: z.string().optional(),
+  last_run: z.number(),
+  next_run: z.number()
+}).passthrough();
+var CatalogConnectionTestResult = z.object({
+  success: z.boolean(),
+  message: z.string().optional()
+}).passthrough();
+var CreateBuildTaskRequest = z.discriminatedUnion("mode", [
+  z.object({
+    resource_id: z.string().min(1),
+    mode: z.literal("batch"),
+    execute_type: BuildTaskExecuteType.optional()
+  }),
+  z.object({
+    resource_id: z.string().min(1),
+    mode: z.literal("streaming"),
+    // Streaming tasks do not have an execution type.
+    execute_type: z.never().optional()
+  })
+]);
 var BuildTask = z.object({
   id: z.string(),
   resource_id: z.string().optional(),
   mode: BuildMode.optional(),
-  status: z.string().optional(),
+  status: BuildTaskStatus.optional(),
   state: z.string().optional(),
   total_count: z.number().optional(),
   synced_count: z.number().optional(),
   vectorized_count: z.number().optional(),
   index_config: z.unknown().optional(),
   catalog_id: z.string().optional(),
+  execute_type: BuildTaskExecuteType.optional(),
+  index_health: z.object({
+    embedding: z.string(),
+    fulltext: z.string(),
+    usable: z.boolean()
+  }).passthrough().optional()
+}).passthrough();
+var BuildTaskSummary = z.object({
+  id: z.string(),
+  resource_id: z.string(),
+  resource_name: z.string().optional(),
+  catalog_id: z.string(),
+  catalog_name: z.string().optional(),
+  status: BuildTaskStatus,
+  mode: BuildMode,
+  execute_type: BuildTaskExecuteType.optional(),
+  total_count: z.number(),
+  synced_count: z.number(),
+  vectorized_count: z.number(),
+  synced_mark: z.string(),
+  error_msg: z.string().optional(),
+  creator: z.object({
+    id: z.string(),
+    name: z.string().optional(),
+    type: z.string()
+  }),
+  create_time: z.number(),
+  update_time: z.number(),
   index_health: z.object({
     embedding: z.string(),
     fulltext: z.string(),
     usable: z.boolean()
   }).passthrough().optional()
 }).passthrough();
+var ListBuildTasksResponse = z.object({
+  entries: z.array(BuildTaskSummary),
+  total_count: z.number()
+}).passthrough();
 async function createBuildTask(ctx, req) {
   const p = CreateBuildTaskRequest.parse(req);
   const body = {
@@ -3226,8 +3668,13 @@ async function createBuildTask(ctx, req) {
   const res = await request(ctx, `${VEGA_BASE}/build-tasks`, { method: "POST", body });
   return BuildTask.parse(res);
 }
-function listBuildTasks(ctx, opts = {}) {
-  return request(ctx, `${VEGA_BASE}/build-tasks`, {
+async function listBuildTasks(ctx, opts = {}) {
+  if (opts.orderBy === "default") {
+    throw new InputError(
+      'orderBy "default" is no longer supported; use "created_at" or "updated_at"'
+    );
+  }
+  const res = await request(ctx, `${VEGA_BASE}/build-tasks`, {
     query: {
       limit: opts.limit,
       offset: opts.offset,
@@ -3240,6 +3687,7 @@ function listBuildTasks(ctx, opts = {}) {
       order: opts.order
     }
   });
+  return ListBuildTasksResponse.parse(res);
 }
 async function getBuildTask(ctx, taskId) {
   const res = await request(ctx, `${VEGA_BASE}/build-tasks/${encodeURIComponent(taskId)}`);
@@ -3290,35 +3738,46 @@ async function listCatalogs(ctx, opts = {}) {
 function getCatalog(ctx, id) {
   return request(ctx, `${VEGA_BASE}/catalogs/${encodeURIComponent(id)}`);
 }
-function createCatalog(ctx, req) {
+function createCatalog(ctx, req, opts = {}) {
   return request(ctx, `${VEGA_BASE}/catalogs`, {
     method: "POST",
+    query: {
+      allow_unhealthy: opts.allowUnhealthy === void 0 ? void 0 : String(opts.allowUnhealthy)
+    },
     body: {
       ...req.id ? { id: req.id } : {},
       name: req.name,
       connector_type: req.connectorType,
       connector_config: req.connectorConfig,
-      ...req.tags ? { tags: req.tags } : {},
-      ...req.description ? { description: req.description } : {},
+      ...req.tags !== void 0 ? { tags: req.tags } : {},
+      ...req.description !== void 0 ? { description: req.description } : {},
       ...req.enabled !== void 0 ? { enabled: req.enabled } : {},
       ...req.internal !== void 0 ? { internal: req.internal } : {},
-      ...req.extensions ? { extensions: req.extensions } : {}
-    }
+      ...req.extensions !== void 0 ? { extensions: req.extensions } : {},
+      ...req.healthCheckSchedule !== void 0 ? {
+        health_check_schedule: req.healthCheckSchedule === null ? null : mapCatalogHealthCheckScheduleRequest(req.healthCheckSchedule)
+      } : {}
+    },
+    timeoutMs: 6e4
   });
 }
-function updateCatalog(ctx, id, req) {
+function updateCatalog(ctx, id, req, opts = {}) {
   return request(ctx, `${VEGA_BASE}/catalogs/${encodeURIComponent(id)}`, {
     method: "PUT",
+    query: {
+      allow_unhealthy: opts.allowUnhealthy === void 0 ? void 0 : String(opts.allowUnhealthy)
+    },
     body: {
-      ...req.id ? { id: req.id } : {},
-      ...req.name ? { name: req.name } : {},
-      ...req.connectorType ? { connector_type: req.connectorType } : {},
+      id,
+      name: req.name,
+      connector_type: req.connectorType,
+      enabled: req.enabled,
       ...req.connectorConfig !== void 0 ? { connector_config: req.connectorConfig } : {},
-      ...req.tags ? { tags: req.tags } : {},
+      ...req.tags !== void 0 ? { tags: req.tags } : {},
       ...req.description !== void 0 ? { description: req.description } : {},
-      ...req.enabled !== void 0 ? { enabled: req.enabled } : {},
-      ...req.extensions ? { extensions: req.extensions } : {}
-    }
+      ...req.extensions !== void 0 ? { extensions: req.extensions } : {}
+    },
+    timeoutMs: 6e4
   });
 }
 function enableCatalog(ctx, id) {
@@ -3332,10 +3791,51 @@ function disableCatalog(ctx, id) {
 function deleteCatalog(ctx, id) {
   return request(ctx, `${VEGA_BASE}/catalogs/${encodeURIComponent(id)}`, { method: "DELETE" });
 }
-function testCatalogConnection(ctx, id) {
-  return request(ctx, `${VEGA_BASE}/catalogs/${encodeURIComponent(id)}/test-connection`, {
-    method: "POST"
+async function testCatalogConnectionConfig(ctx, req) {
+  const result = await request(ctx, `${VEGA_BASE}/catalogs/test-connection`, {
+    method: "POST",
+    body: {
+      connector_type: req.connectorType,
+      connector_config: req.connectorConfig
+    },
+    timeoutMs: 6e4
   });
+  return CatalogConnectionTestResult.parse(result);
+}
+async function testCatalogConnection(ctx, id) {
+  const result = await request(
+    ctx,
+    `${VEGA_BASE}/catalogs/${encodeURIComponent(id)}/test-connection`,
+    {
+      method: "POST",
+      timeoutMs: 6e4
+    }
+  );
+  return CatalogConnectionTestResult.parse(result);
+}
+async function getCatalogHealthCheckSchedule(ctx, id) {
+  const result = await request(
+    ctx,
+    `${VEGA_BASE}/catalogs/${encodeURIComponent(id)}/health-check-schedule`
+  );
+  return CatalogHealthCheckSchedule.parse(result);
+}
+async function updateCatalogHealthCheckSchedule(ctx, id, req) {
+  const result = await request(
+    ctx,
+    `${VEGA_BASE}/catalogs/${encodeURIComponent(id)}/health-check-schedule`,
+    {
+      method: "PUT",
+      body: mapCatalogHealthCheckScheduleRequest(req)
+    }
+  );
+  return CatalogHealthCheckSchedule.parse(result);
+}
+function mapCatalogHealthCheckScheduleRequest(req) {
+  return {
+    mode: req.mode,
+    ...req.mode === "enabled" ? { cron_expr: req.cronExpr } : {}
+  };
 }
 function discoverCatalog(ctx, id, wait = true) {
   return request(ctx, `${VEGA_BASE}/catalogs/${encodeURIComponent(id)}/discover`, {
@@ -3355,11 +3855,12 @@ function listCatalogResources(ctx, id, category, limit, offset) {
     }
   });
 }
-function catalogHealthStatus(ctx, ids) {
-  return request(
+async function catalogHealthStatus(ctx, id) {
+  const result = await request(
     ctx,
-    `${VEGA_BASE}/catalogs/${ids.map(encodeURIComponent).join(",")}/health-status`
+    `${VEGA_BASE}/catalogs/${encodeURIComponent(id)}/health-status`
   );
+  return CatalogHealthStatus.parse(result);
 }
 function listConnectorTypes(ctx) {
   return request(ctx, `${VEGA_BASE}/connector-types`, { query: { sort: "name", order: "asc" } });
@@ -4273,16 +4774,45 @@ async function updateSkillPackageZip(ctx, skillId, bytes, filename = "skill.zip"
   if (!res.ok) throw new HttpError(res.status, res.statusText, text);
   return text ? JSON.parse(text) : void 0;
 }
-async function downloadSkill(ctx, skillId) {
+function skillPath(skillId, view, path) {
+  const seg = view === "draft" ? "management/" : "";
+  return `${BASE5}/skills/${encodeURIComponent(skillId)}/${seg}${path}`;
+}
+async function downloadSkill(ctx, skillId, view = "published") {
   const res = await authFetch(
     ctx,
-    () => tlsFetch(ctx.insecure, `${ctx.baseUrl}${BASE5}/skills/${encodeURIComponent(skillId)}/download`, {
+    () => tlsFetch(ctx.insecure, `${ctx.baseUrl}${skillPath(skillId, view, "download")}`, {
       headers: buildHeaders(ctx)
     })
   );
   if (!res.ok) throw new HttpError(res.status, res.statusText, await res.text());
   return new Uint8Array(await res.arrayBuffer());
 }
+function executeSkill(ctx, skillId, opts) {
+  return request(ctx, `${BASE5}/skills/${encodeURIComponent(skillId)}/execute`, {
+    method: "POST",
+    body: {
+      entry_shell: opts.entryShell,
+      ...opts.timeout === void 0 ? {} : { timeout: opts.timeout }
+    },
+    // Outlast the sandbox: the default client timeout is shorter than the run
+    // budget, so without this a long run aborts locally mid-execution and the
+    // caller never learns the exit code. With no stated limit the sandbox
+    // applies its own — 300s by default, 3600s at most — so the budget has to
+    // cover that rather than a number of ours.
+    timeoutMs: executeBudgetMs(opts.timeout),
+    // The abort deadline alone tops out at undici's 300s header deadline,
+    // because `execute-sync` blocks and sends no headers until the run is over.
+    headersTimeoutMs: executeBudgetMs(opts.timeout)
+  });
+}
+var SANDBOX_MAX_TIMEOUT_SEC = 3600;
+function executeBudgetMs(timeoutSec) {
+  return (timeoutSec ?? SANDBOX_MAX_TIMEOUT_SEC) * 1e3 + 15e3;
+}
+function getSkillNames(ctx, ids) {
+  return request(ctx, `${BASE5}/skills/names`, { method: "POST", body: { ids } });
+}
 function updateSkillMetadata(ctx, skillId, body) {
   return request(ctx, `${BASE5}/skills/${encodeURIComponent(skillId)}`, { method: "PUT", body });
 }
@@ -4323,12 +4853,15 @@ function getSkillMarket(ctx, skillId) {
 function deleteSkill(ctx, skillId) {
   return request(ctx, `${BASE5}/skills/${encodeURIComponent(skillId)}`, { method: "DELETE" });
 }
-function getSkillContent(ctx, skillId) {
-  return request(ctx, `${BASE5}/skills/${encodeURIComponent(skillId)}/content`);
+function getSkillContent(ctx, skillId, opts = {}) {
+  return request(ctx, skillPath(skillId, opts.view ?? "published", "content"), {
+    query: { response_mode: opts.responseMode }
+  });
 }
-function readSkillFile(ctx, skillId, relPath) {
-  return request(ctx, `${BASE5}/skills/${encodeURIComponent(skillId)}/files/read`, {
+function readSkillFile(ctx, skillId, relPath, opts = {}) {
+  return request(ctx, skillPath(skillId, opts.view ?? "published", "files/read"), {
     method: "POST",
+    query: { response_mode: opts.responseMode },
     body: { rel_path: relPath }
   });
 }
@@ -4366,6 +4899,15 @@ async function zipDirectory(dir) {
   }
   return new Uint8Array(await zip.generateAsync({ type: "uint8array", compression: "DEFLATE" }));
 }
+async function unzipToMap(bytes) {
+  const zip = await JSZip.loadAsync(bytes);
+  const out = /* @__PURE__ */ new Map();
+  for (const entry of Object.values(zip.files)) {
+    if (entry.dir) continue;
+    out.set(entry.name, new Uint8Array(await entry.async("uint8array")));
+  }
+  return out;
+}
 async function unzipToDirectory(bytes, dir) {
   const abs = resolve4(dir);
   mkdirSync3(abs, { recursive: true });
@@ -4382,16 +4924,202 @@ async function unzipToDirectory(bytes, dir) {
   return written;
 }
 
+// src/utils/skill-tree.ts
+function normalize(path) {
+  return (path ?? "").replace(/^\/+|\/+$/g, "");
+}
+function segments(relPath) {
+  return relPath.split("/").filter(Boolean);
+}
+function classifyPath(files, path) {
+  const target = normalize(path);
+  if (!target) return "root";
+  if (files.some((f) => normalize(f.rel_path) === target)) return "file";
+  const prefix = `${target}/`;
+  return files.some((f) => normalize(f.rel_path).startsWith(prefix)) ? "dir" : "missing";
+}
+function listChildren(files, path) {
+  const target = normalize(path);
+  const prefix = target ? `${target}/` : "";
+  const dirs = /* @__PURE__ */ new Map();
+  const leaves = [];
+  for (const file of files) {
+    const rel = normalize(file.rel_path);
+    if (prefix && !rel.startsWith(prefix)) continue;
+    const rest = segments(rel.slice(prefix.length));
+    if (rest.length === 0) continue;
+    const [head] = rest;
+    if (!head) continue;
+    if (rest.length === 1) {
+      leaves.push({
+        name: head,
+        type: "file",
+        relPath: rel,
+        fileType: file.file_type,
+        size: file.size,
+        mime: file.mime_type
+      });
+      continue;
+    }
+    const dir = dirs.get(head) ?? { name: head, type: "dir", files: 0, size: 0 };
+    dir.files += 1;
+    dir.size += file.size ?? 0;
+    dirs.set(head, dir);
+  }
+  const byName = (a, b) => a.name.localeCompare(b.name);
+  return [...[...dirs.values()].sort(byName), ...leaves.sort(byName)];
+}
+function filesUnder(files, path) {
+  const target = normalize(path);
+  if (!target) return files;
+  const prefix = `${target}/`;
+  return files.filter((f) => normalize(f.rel_path).startsWith(prefix));
+}
+function emptyNode() {
+  return { dirs: /* @__PURE__ */ new Map(), files: [] };
+}
+function buildTree(files) {
+  const root = emptyNode();
+  for (const file of files) {
+    const parts = segments(normalize(file.rel_path));
+    const name = parts.pop();
+    if (!name) continue;
+    let node = root;
+    for (const part of parts) {
+      const next = node.dirs.get(part) ?? emptyNode();
+      node.dirs.set(part, next);
+      node = next;
+    }
+    node.files.push({
+      name,
+      type: "file",
+      relPath: normalize(file.rel_path),
+      fileType: file.file_type,
+      size: file.size,
+      mime: file.mime_type
+    });
+  }
+  return root;
+}
+function renderNode(node, indent, out) {
+  const dirs = [...node.dirs.entries()].sort(([a], [b]) => a.localeCompare(b));
+  const files = [...node.files].sort((a, b) => a.name.localeCompare(b.name));
+  const total = dirs.length + files.length;
+  let index = 0;
+  for (const [name, child] of dirs) {
+    index += 1;
+    const last = index === total;
+    out.push(`${indent}${last ? "\u2514\u2500\u2500 " : "\u251C\u2500\u2500 "}${name}/`);
+    renderNode(child, `${indent}${last ? "    " : "\u2502   "}`, out);
+  }
+  for (const file of files) {
+    index += 1;
+    const last = index === total;
+    const meta = [file.fileType, file.size === void 0 ? void 0 : `${file.size} B`].filter(Boolean).join(", ");
+    out.push(`${indent}${last ? "\u2514\u2500\u2500 " : "\u251C\u2500\u2500 "}${file.name}${meta ? `  (${meta})` : ""}`);
+  }
+}
+function renderTree(files) {
+  const out = [];
+  renderNode(buildTree(files), "", out);
+  return out.join("\n");
+}
+
 // src/resources/skills.ts
+function viewOf(opts) {
+  return opts?.draft ? "draft" : "published";
+}
+function cachedArchive(cache, ctx, skillId, view) {
+  const key = `${skillId}|${view}`;
+  const hit = cache.get(key);
+  if (hit) return hit;
+  const pending = downloadSkill(ctx, skillId, view).then(unzipToMap);
+  cache.set(key, pending);
+  pending.catch(() => cache.delete(key));
+  return pending;
+}
+function binaryError(relPath) {
+  return new InputError(
+    `'${relPath}' is a binary file \u2014 use \`openbkn skill install\` or \`skill download\` to fetch it.`
+  );
+}
+function decodeStrict(bytes, relPath) {
+  let text;
+  try {
+    text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+    throw binaryError(relPath);
+  }
+  if (text.includes("\0")) throw binaryError(relPath);
+  return text;
+}
+function looksLossy(text) {
+  return text.includes("\0") || text.includes("\uFFFD");
+}
+async function readFileText(cache, ctx, skillId, relPath, view) {
+  const res = await readSkillFile(ctx, skillId, normalize(relPath), {
+    view,
+    responseMode: "content"
+  });
+  if (typeof res?.content === "string" && res.content.length > 0) {
+    if (looksLossy(res.content)) throw binaryError(relPath);
+    return res.content;
+  }
+  const archive = await cachedArchive(cache, ctx, skillId, view);
+  const bytes = archive.get(normalize(relPath));
+  if (!bytes) {
+    throw new InputError(`'${relPath}' not found in skill ${skillId}.`);
+  }
+  return decodeStrict(bytes, relPath);
+}
 function skills(ctx) {
+  const archives = /* @__PURE__ */ new Map();
+  const manifest = async (skillId, opts) => {
+    const res = await getSkillContent(ctx, skillId, { view: viewOf(opts) });
+    return res?.files ?? [];
+  };
   return {
     list: (opts) => listSkills(ctx, opts),
     get: (skillId) => getSkill(ctx, skillId),
     market: (opts) => listSkillMarket(ctx, opts),
     marketGet: (skillId) => getSkillMarket(ctx, skillId),
     delete: (skillId) => deleteSkill(ctx, skillId),
-    content: (skillId) => getSkillContent(ctx, skillId),
-    readFile: (skillId, relPath) => readSkillFile(ctx, skillId, relPath),
+    content: (skillId, opts) => getSkillContent(ctx, skillId, { view: viewOf(opts) }),
+    // Normalized like every other path entry point, so `/a/b.md` addresses the
+    // same file here as it does under `--raw` and in `skill files`.
+    readFile: (skillId, relPath, opts) => readSkillFile(ctx, skillId, normalize(relPath), { view: viewOf(opts) }),
+    /** SKILL.md's own text, for callers that want the document rather than a link. */
+    contentRaw: (skillId, opts) => readFileText(archives, ctx, skillId, "SKILL.md", viewOf(opts)),
+    /** A bundled file's text. */
+    readFileRaw: (skillId, relPath, opts) => readFileText(archives, ctx, skillId, relPath, viewOf(opts)),
+    /** Run the skill in the platform sandbox. */
+    execute: (skillId, opts) => executeSkill(ctx, skillId, opts),
+    /** Resolve skill ids to names; unknown ids are simply absent from the result. */
+    names: (ids) => getSkillNames(ctx, ids),
+    /**
+     * One level of the skill's file tree. Directories are inferred from the
+     * manifest's paths — see utils/skill-tree.
+     */
+    files: async (skillId, path, opts) => {
+      const files = await manifest(skillId, opts);
+      const kind = classifyPath(files, path);
+      if (kind === "file") {
+        throw new InputError(`'${path}' is a file, not a directory \u2014 use \`skill read-file\`.`);
+      }
+      if (kind === "missing") {
+        throw new InputError(`'${path}' not found in skill ${skillId}.`);
+      }
+      const subtree = filesUnder(files, path);
+      return {
+        skillId,
+        path: path ?? "",
+        entries: listChildren(files, path),
+        totalFiles: subtree.length,
+        totalSize: subtree.reduce((sum, f) => sum + (f.size ?? 0), 0)
+      };
+    },
+    /** The manifest itself, for callers that want to render the whole tree. */
+    fileManifest: manifest,
     history: (skillId) => getSkillHistory(ctx, skillId),
     setStatus: (skillId, status2) => setSkillStatus(ctx, skillId, status2),
     updateMetadata: (skillId, body) => updateSkillMetadata(ctx, skillId, body),
@@ -4405,16 +5133,16 @@ function skills(ctx) {
     /** Replace a skill's package from a local directory. */
     updatePackage: async (skillId, dir) => updateSkillPackageZip(ctx, skillId, await zipDirectory(dir), `${basename2(resolve5(dir))}.zip`),
     /** Download a skill archive to a local .zip file. */
-    download: async (skillId, outPath) => {
-      const bytes = await downloadSkill(ctx, skillId);
+    download: async (skillId, outPath, opts) => {
+      const bytes = await downloadSkill(ctx, skillId, viewOf(opts));
       const dest = resolve5(outPath ?? `${skillId}.zip`);
       mkdirSync4(dirname3(dest), { recursive: true });
       writeFileSync3(dest, bytes);
       return { skillId, path: dest, bytes: bytes.length };
     },
     /** Download a skill archive and extract it into a directory. */
-    install: async (skillId, dir) => {
-      const bytes = await downloadSkill(ctx, skillId);
+    install: async (skillId, dir, opts) => {
+      const bytes = await downloadSkill(ctx, skillId, viewOf(opts));
       const target = resolve5(dir ?? skillId);
       const files = await unzipToDirectory(bytes, target);
       return { skillId, dir: target, files: files.length };
@@ -4576,727 +5304,384 @@ function toolboxes(ctx) {
   };
 }
 
-// src/trace-session.ts
-import { randomUUID as randomUUID2 } from "crypto";
-var PAYLOAD_FIELDS = {
-  "agent.interaction.started": /* @__PURE__ */ new Set([
-    "intent_hash",
-    "mode",
-    "agent_id",
-    "app_ref",
-    "question_artifact_ref"
-  ]),
-  "retrieval.completed": /* @__PURE__ */ new Set([
-    "query_hash",
-    "candidate_count",
-    "truncated",
-    "version_status",
-    "source_refs"
-  ]),
-  "knowledge.read.observed": /* @__PURE__ */ new Set([
-    "kn_id",
-    "read_kind",
-    "version_status",
-    "schema_version",
-    "business_refs"
-  ]),
-  "data.query.observed": /* @__PURE__ */ new Set([
-    "query_hash",
-    "query_type",
-    "row_count",
-    "truncated",
-    "as_of",
-    "version_status",
-    "resource_refs",
-    "field_refs",
-    "query_artifact_ref",
-    "result_artifact_ref"
-  ]),
-  "logic.execution.observed": /* @__PURE__ */ new Set([
-    "logic_ref",
-    "input_artifact_ref",
-    "result_artifact_ref",
-    "status"
-  ]),
-  "model.call.observed": /* @__PURE__ */ new Set([
-    "model_name",
-    "model_provider",
-    "status",
-    "input_token_count",
-    "output_token_count",
-    "prompt_hash",
-    "output_hash",
-    "error_category",
-    "error_hash"
-  ]),
-  "tool.called": /* @__PURE__ */ new Set(["tool_id", "tool_name", "args_hash", "visibility", "version_status"]),
-  "tool.result.observed": /* @__PURE__ */ new Set([
-    "tool_id",
-    "tool_name",
-    "status",
-    "result_hash",
-    "result_length",
-    "result_count",
-    "error_hash",
-    "error_category",
-    "visibility",
-    "version_status"
-  ]),
-  "claim.created": /* @__PURE__ */ new Set([
-    "claim_id",
-    "claim_type",
-    "claim_hash",
-    "source_event_ids",
-    "operation_ids",
-    "visibility",
-    "version_status",
-    "result_artifact_ref"
-  ]),
-  "evidence.refs.created": /* @__PURE__ */ new Set(["claim_id", "evidence_refs"]),
-  "business.refs.resolved": /* @__PURE__ */ new Set(["claim_id", "resolver_status", "business_refs"]),
-  "action.recommended": /* @__PURE__ */ new Set([
-    "action_instance_id",
-    "action_type",
-    "target_refs",
-    "reason_hash",
-    "status",
-    "reason_artifact_ref",
-    "input_artifact_ref"
-  ]),
-  "action.approval_requested": /* @__PURE__ */ new Set(["action_instance_id", "policy_ref", "status"]),
-  "action.approved": /* @__PURE__ */ new Set(["action_instance_id", "actor_ref", "policy_decision_ref", "status"]),
-  "action.rejected": /* @__PURE__ */ new Set(["action_instance_id", "actor_ref", "policy_decision_ref", "status"]),
-  "action.executed": /* @__PURE__ */ new Set([
-    "action_instance_id",
-    "status",
-    "invocation_ref",
-    "error_category",
-    "error_hash"
-  ]),
-  "action.result_recorded": /* @__PURE__ */ new Set([
-    "action_instance_id",
-    "status",
-    "result_hash",
-    "task_ref",
-    "artifact_ref",
-    "result_artifact_ref"
-  ])
-};
-var REQUIRED_PAYLOAD_FIELDS = {
-  "agent.interaction.started": ["intent_hash", "mode"],
-  "retrieval.completed": ["query_hash", "candidate_count", "truncated"],
-  "knowledge.read.observed": ["kn_id", "read_kind", "version_status"],
-  "data.query.observed": ["query_hash", "query_type", "row_count"],
-  "logic.execution.observed": ["logic_ref", "input_artifact_ref", "result_artifact_ref", "status"],
-  "model.call.observed": [
-    "model_name",
-    "model_provider",
-    "status",
-    "input_token_count",
-    "output_token_count",
-    "prompt_hash",
-    "output_hash"
-  ],
-  "tool.called": ["tool_id", "tool_name", "args_hash", "visibility", "version_status"],
-  "tool.result.observed": ["tool_id", "tool_name", "status", "visibility", "version_status"],
-  "claim.created": [
-    "claim_id",
-    "claim_type",
-    "claim_hash",
-    "source_event_ids",
-    "operation_ids",
-    "visibility",
-    "version_status"
-  ],
-  "evidence.refs.created": ["claim_id", "evidence_refs"],
-  "business.refs.resolved": ["claim_id", "resolver_status", "business_refs"],
-  "action.recommended": [
-    "action_instance_id",
-    "action_type",
-    "target_refs",
-    "reason_hash",
-    "status"
-  ],
-  "action.approval_requested": ["action_instance_id", "policy_ref", "status"],
-  "action.approved": ["action_instance_id", "actor_ref", "policy_decision_ref", "status"],
-  "action.rejected": ["action_instance_id", "actor_ref", "policy_decision_ref", "status"],
-  "action.executed": ["action_instance_id", "status", "invocation_ref"],
-  "action.result_recorded": ["action_instance_id", "status", "result_hash"]
-};
-var REF_FIELDS = /* @__PURE__ */ new Set([
-  "ref_id",
-  "ref_type",
-  "source_system",
-  "validity",
-  "version_status",
-  "visibility",
-  "summary_hash"
+// src/api/trace-lifecycle.ts
+var LIFECYCLE = "/api/agent-observability/v1";
+var FORBIDDEN_INPUT_FIELDS = /* @__PURE__ */ new Set([
+  "generation",
+  "on_behalf_of",
+  "onBehalfOf",
+  "owner",
+  "tenant_id",
+  "application_principal_id",
+  "actor_subject",
+  "actor_subject_type",
+  "actor_subject_id",
+  "effective_subject",
+  "effective_subject_type",
+  "effective_subject_id",
+  "delegation_id"
 ]);
-var RAW_KEYS = /* @__PURE__ */ new Set([
-  "authorization",
-  "cookie",
-  "access_token",
-  "refresh_token",
-  "id_token",
-  "api_key",
-  "password",
-  "private_key",
-  "prompt",
-  "user_question",
-  "approval_comment",
-  "sql",
-  "query_params",
-  "rows"
-]);
-var HASH_RE = /^sha256:[0-9a-f]{64}$/;
-var RAW_VALUE_PATTERNS = [
-  /bearer\s+[A-Za-z0-9._-]+/i,
-  /\bselect\s+.+\s+from\b/is,
-  /\binsert\s+into\b/i,
-  /\bupdate\s+\S+\s+set\b/i,
-  /\bdelete\s+from\b/i,
-  /[\w.+-]+@[\w.-]+\.[A-Za-z]{2,}/,
-  /https?:\/\/[^\s"']+/i
-];
-function defaultNow() {
-  return (/* @__PURE__ */ new Date()).toISOString();
-}
-function assertSessionOptions(options) {
-  const trace2 = options.trace;
-  if (!/^[0-9a-f]{32}$/.test(trace2.trace_id)) throw new Error("trace_id must be 32 hex characters");
-  const traceparent = /^00-([0-9a-f]{32})-[0-9a-f]{16}-[0-9a-f]{2}$/.exec(trace2.traceparent);
-  if (!traceparent || traceparent[1] !== trace2.trace_id) {
-    throw new Error("traceparent must be valid and match trace_id");
-  }
-  if (!/^req_[0-9A-Za-z_.-]+$/.test(trace2["bkn.request.id"])) {
-    throw new Error("bkn.request.id must start with req_");
-  }
-  const conversationId = options.conversationId ?? trace2["bkn.conversation.id"];
-  if (conversationId && !/^[0-9A-Za-z_.:-]{1,128}$/.test(conversationId)) {
-    throw new Error("conversationId must be an opaque correlation identifier");
-  }
-  if (options.conversationId && trace2["bkn.conversation.id"] && options.conversationId !== trace2["bkn.conversation.id"]) {
-    throw new Error("conversationId conflicts with trace bkn.conversation.id");
-  }
-  if (!trace2["bkn.tenant.id"] && !trace2.business_domain) {
-    throw new Error("trace requires bkn.tenant.id or business_domain");
-  }
-  if (!trace2["bkn.account.id"] || !trace2["bkn.account.type"]) {
-    throw new Error("trace requires account id and type");
-  }
-  if (!/^[0-9a-f]{16}$/.test(options.spanId)) throw new Error("spanId must be 16 hex characters");
-  if (!options.producerModule.trim()) throw new Error("producerModule is required");
-}
-function clone(value) {
-  return JSON.parse(JSON.stringify(value));
-}
-function assertSafePayload(eventType, payload) {
-  const allowed = PAYLOAD_FIELDS[eventType];
-  for (const key of Object.keys(payload)) {
-    if (!allowed.has(key)) throw new Error(`${eventType} payload field is not registered: ${key}`);
-  }
-  for (const key of REQUIRED_PAYLOAD_FIELDS[eventType] ?? []) {
-    if (payload[key] === void 0 || payload[key] === "") {
-      throw new Error(`${eventType} payload requires ${key}`);
-    }
-  }
-  if (eventType === "agent.interaction.started" && !payload.agent_id && !payload.app_ref) {
-    throw new Error("agent.interaction.started requires agent_id or app_ref");
-  }
-  if (eventType === "agent.interaction.started") {
-    assertEnum(payload, "mode", ["chat", "task", "background"]);
-  }
-  if (eventType === "model.call.observed" || eventType === "action.executed") {
-    assertEnum(payload, "status", ["ok", "error"]);
-  }
-  if (eventType === "model.call.observed" && payload.status === "error") {
-    for (const key of ["error_category", "error_hash"]) {
-      if (!payload[key]) throw new Error(`model.call.observed error requires ${key}`);
-    }
-  }
-  if (eventType === "tool.result.observed") {
-    assertEnum(payload, "status", ["success", "error"]);
-    if (payload.status === "success" && !payload.result_hash) {
-      throw new Error("tool.result.observed success requires result_hash");
-    }
-    if (payload.status === "error" && !payload.error_hash) {
-      throw new Error("tool.result.observed error requires error_hash");
-    }
-  }
-  if (eventType === "business.refs.resolved") {
-    assertEnum(payload, "resolver_status", ["resolved", "partial", "unresolved"]);
-  }
-  for (const key of ["source_event_ids", "operation_ids", "target_refs"]) {
-    if (key in payload && (!Array.isArray(payload[key]) || payload[key].length === 0)) {
-      throw new Error(`${eventType} payload requires non-empty ${key}`);
-    }
-  }
-  if (eventType === "action.recommended") {
-    for (const ref of payload.target_refs) assertQualifiedReference(ref);
-  }
-  if (eventType === "evidence.refs.created") {
-    assertRefs(payload.evidence_refs, false);
-  }
-  if (eventType === "business.refs.resolved") {
-    const unresolved = payload.resolver_status === "unresolved";
-    assertRefs(payload.business_refs, unresolved);
-  }
-  if (eventType === "action.result_recorded" && !payload.task_ref && !payload.artifact_ref && !payload.result_artifact_ref) {
-    throw new Error(
-      "action.result_recorded requires task_ref, artifact_ref, or result_artifact_ref"
-    );
-  }
-  if (eventType === "action.executed" && payload.status === "error") {
-    for (const key of ["error_category", "error_hash"]) {
-      if (!payload[key]) throw new Error(`action.executed error requires ${key}`);
-    }
-  }
-  const fixedStatus = {
-    "action.recommended": "recommended",
-    "action.approval_requested": "approval_requested",
-    "action.approved": "approved",
-    "action.rejected": "rejected"
+function traceLifecycleApi(ctx) {
+  const post2 = async (path, input) => {
+    assertNoForbiddenInputFields(input);
+    return await request(ctx, `${LIFECYCLE}${path}`, { method: "POST", body: input });
+  };
+  const get = (path) => request(ctx, `${LIFECYCLE}${path}`, { method: "GET" });
+  const interactionTerminal = (interactionId, action, input) => post2(`/interactions/${encodeURIComponent(interactionId)}/${action}`, input);
+  const finishAttempt = (operationId, attempt, action, input) => post2(
+    `/operations/${encodeURIComponent(operationId)}/attempts/${encodeURIComponent(String(attempt))}:${action}`,
+    input
+  );
+  return {
+    listConversations: (query = {}) => {
+      const params = new URLSearchParams();
+      if (query.limit !== void 0 && Number.isFinite(query.limit)) {
+        params.set("limit", String(query.limit));
+      }
+      const suffix = params.size > 0 ? `?${params.toString()}` : "";
+      return get(`/conversations${suffix}`);
+    },
+    ensureConversation: (input) => post2("/conversations:ensure-current", input),
+    createNewConversationGeneration: (input) => post2("/conversations:create-new-generation", input),
+    resumeConversation: (input) => post2("/conversations:resume-by-id", input),
+    getConversation: (conversationId) => get(`/conversations/${encodeURIComponent(conversationId)}`),
+    closeConversation: (conversationId, input) => post2(`/conversations/${encodeURIComponent(conversationId)}/close`, input),
+    startInteraction: (conversationId, input) => post2(`/conversations/${encodeURIComponent(conversationId)}/interactions`, input),
+    getInteraction: (interactionId) => get(`/interactions/${encodeURIComponent(interactionId)}`),
+    completeInteraction: (interactionId, input) => interactionTerminal(interactionId, "complete", input),
+    failInteraction: (interactionId, input) => interactionTerminal(interactionId, "fail", input),
+    cancelInteraction: (interactionId, input) => interactionTerminal(interactionId, "cancel", input),
+    handoffInteraction: (interactionId, input) => interactionTerminal(interactionId, "handoff", input),
+    ensureOperation: (conversationId, interactionId, input) => post2(
+      `/conversations/${encodeURIComponent(conversationId)}/interactions/${encodeURIComponent(interactionId)}/operations:ensure`,
+      input
+    ),
+    getOperation: (operationId) => get(`/operations/${encodeURIComponent(operationId)}`),
+    retryOperationAttempt: (operationId, input) => post2(`/operations/${encodeURIComponent(operationId)}/attempts`, input),
+    completeOperationAttempt: (operationId, attempt, input) => finishAttempt(operationId, attempt, "complete", input),
+    failOperationAttempt: (operationId, attempt, input) => finishAttempt(operationId, attempt, "fail", input),
+    getReceipt: (receiptId) => get(`/receipts/${encodeURIComponent(receiptId)}`)
   };
-  if (fixedStatus[eventType] && payload.status !== fixedStatus[eventType]) {
-    throw new Error(`${eventType} requires status=${fixedStatus[eventType]}`);
-  }
-  scanSafeValue(payload, "payload");
-}
-function assertRefs(value, allowEmpty) {
-  if (!Array.isArray(value) || !allowEmpty && value.length === 0) {
-    throw new Error("reference list must be a non-empty array");
-  }
-  for (const item of value) {
-    if (!item || typeof item !== "object" || Array.isArray(item)) {
-      throw new Error("reference must be an object");
-    }
-    const ref = item;
-    for (const key of Object.keys(ref)) {
-      if (!REF_FIELDS.has(key)) throw new Error(`reference field is not registered: ${key}`);
-    }
-    for (const key of [
-      "ref_id",
-      "ref_type",
-      "source_system",
-      "validity",
-      "version_status",
-      "visibility"
-    ]) {
-      if (!ref[key]) throw new Error(`reference requires ${key}`);
-    }
-    assertQualifiedReference(String(ref.ref_id));
-    assertEnum(ref, "validity", ["observed", "available", "unavailable", "expired", "partial"]);
-    assertEnum(ref, "version_status", ["versioned", "unversioned", "not_auditable"]);
-    assertEnum(ref, "visibility", [
-      "visible",
-      "redacted",
-      "hidden",
-      "omitted",
-      "unresolved",
-      "unauthorized"
-    ]);
-  }
-}
-function assertQualifiedReference(value) {
-  const parts = value.trim().split(":");
-  const namespace = parts[0] ?? "";
-  let valid = parts.every((part) => part.length > 0);
-  if (["kn", "resource"].includes(namespace)) valid = valid && parts.length === 2;
-  if (["object", "relation", "action_type", "metric", "field"].includes(namespace)) {
-    valid = valid && parts.length === 3;
-  }
-  if (namespace === "property") valid = valid && parts.length === 4;
-  if (!valid) {
-    throw new Error("business reference id must include its knowledge-network or resource scope");
-  }
-}
-function assertEnum(value, key, allowed) {
-  if (!allowed.includes(String(value[key]))) {
-    throw new Error(`${key} must be one of ${allowed.join(", ")}`);
-  }
 }
-function scanSafeValue(value, path) {
-  if (Array.isArray(value)) {
-    value.forEach((child, index) => scanSafeValue(child, `${path}[${index}]`));
-    return;
-  }
-  if (value && typeof value === "object") {
-    for (const [key, child] of Object.entries(value)) {
-      if (RAW_KEYS.has(key.toLowerCase())) throw new Error(`raw sensitive payload field: ${key}`);
-      if (key.endsWith("_hash") && child !== "" && !HASH_RE.test(String(child))) {
-        throw new Error(`${path}.${key} must be a sha256 hash`);
+function assertNoForbiddenInputFields(input) {
+  const pending = [input];
+  const seen = /* @__PURE__ */ new Set();
+  while (pending.length > 0) {
+    const value = pending.pop();
+    if (typeof value !== "object" || value === null || seen.has(value)) continue;
+    seen.add(value);
+    for (const [field, nested] of Object.entries(value)) {
+      if (FORBIDDEN_INPUT_FIELDS.has(field)) {
+        throw new InputError(`Lifecycle input field "${field}" is not allowed`);
       }
-      scanSafeValue(child, `${path}.${key}`);
+      pending.push(nested);
     }
-    return;
-  }
-  if (typeof value === "string" && RAW_VALUE_PATTERNS.some((pattern) => pattern.test(value))) {
-    throw new Error(`raw sensitive payload value at ${path}`);
   }
 }
-var TraceSession = class {
-  interactionId;
-  trace;
-  producerModule;
-  spanId;
-  emit;
-  contractVersion;
+
+// src/managed-trace.ts
+import { randomUUID as randomUUID3 } from "crypto";
+var FORBIDDEN_INPUT_FIELDS2 = ["generation", "on_behalf_of", "onBehalfOf"];
+var CompletionMissingError = class extends InputError {
+};
+var OperationFailedError = class extends InputError {
+};
+var ManagedTrace = class {
+  constructor(api, options = {}) {
+    this.api = api;
+    this.idFactory = options.idFactory ?? randomUUID3;
+  }
+  api;
   idFactory;
-  now;
-  events = [];
-  eventIDs = /* @__PURE__ */ new Set();
-  operationIDs = /* @__PURE__ */ new Set();
-  claimEventIDs = /* @__PURE__ */ new Map();
-  actions = /* @__PURE__ */ new WeakMap();
-  flushTail = Promise.resolve();
-  constructor(options) {
-    assertSessionOptions(options);
-    this.trace = clone(options.trace);
-    if (options.conversationId) {
-      this.trace["bkn.conversation.id"] = options.conversationId;
-    }
-    this.producerModule = options.producerModule;
-    this.spanId = options.spanId;
-    this.emit = options.emit;
-    this.contractVersion = options.contractVersion ?? "2.1.0";
-    this.idFactory = options.idFactory ?? randomUUID2;
-    this.now = options.now ?? defaultNow;
-    this.interactionId = options.interactionId ?? this.idFactory();
-  }
-  startInteraction(input) {
-    return this.append("agent.interaction.started", {
-      operationName: input.operationName,
-      payload: {
-        intent_hash: input.intentHash,
-        mode: input.mode,
-        ...input.agentId ? { agent_id: input.agentId } : {},
-        ...input.appRef ? { app_ref: input.appRef } : {},
-        ...input.questionArtifactRef ? { question_artifact_ref: input.questionArtifactRef } : {}
+  pendingConversations = /* @__PURE__ */ new Map();
+  activeConversationIds = /* @__PURE__ */ new Set();
+  async withInteraction(strategy, callback) {
+    assertSafeStrategy(strategy);
+    const conversation = await this.resolveConversation(strategy);
+    if (this.activeConversationIds.has(conversation.conversation_id)) {
+      throw new InputError(
+        `Conversation "${conversation.conversation_id}" already has an active interaction`
+      );
+    }
+    this.activeConversationIds.add(conversation.conversation_id);
+    try {
+      const interaction = await this.api.startInteraction(conversation.conversation_id, {
+        idempotency_key: this.idFactory()
+      });
+      const receipts = /* @__PURE__ */ new Map();
+      let terminal;
+      let terminalAction;
+      const terminalInput = (reason) => ({
+        terminal_idempotency_key: this.idFactory(),
+        lease_token: interaction.lease_token,
+        lease_epoch: interaction.lease_epoch,
+        completion_manifest_version: "3.0.0",
+        completion_reason: reason,
+        claims: [],
+        expected_operations: expectedOperations(receipts.values()),
+        expected_receipts: expectedReceipts(receipts.values())
+      });
+      const scope = {
+        conversation,
+        interaction,
+        bknContext: (operationKey, parentOperationId, causationEventIds) => ({
+          bkn_context: {
+            conversation_id: conversation.conversation_id,
+            interaction_id: interaction.interaction_id,
+            operation_key: operationKey,
+            ...parentOperationId ? { parent_operation_id: parentOperationId } : {},
+            ...causationEventIds?.length ? { causation_event_ids: causationEventIds } : {}
+          }
+        }),
+        recordReceipt: (receipt) => {
+          if (receipt.conversation_id !== conversation.conversation_id || receipt.interaction_id !== interaction.interaction_id) {
+            throw new InputError("Receipt does not belong to the active managed interaction");
+          }
+          receipts.set(receipt.receipt_id, receipt);
+        },
+        supportCandidates: () => [...receipts.values()].flatMap(
+          (receipt) => receipt.observed_evidence_refs.map((ref) => ({
+            ref,
+            state: "observed",
+            adopted: false
+          }))
+        ),
+        runOperation: async (input, execute) => this.runOperation(
+          conversation,
+          interaction,
+          input,
+          execute,
+          scope.bknContext,
+          scope.recordReceipt
+        ),
+        cancel: async (reason) => {
+          terminalAction ??= this.api.cancelInteraction(
+            interaction.interaction_id,
+            terminalInput(reason)
+          );
+          terminal = await terminalAction;
+          return terminal;
+        },
+        handoff: async (reason) => {
+          terminalAction ??= this.api.handoffInteraction(
+            interaction.interaction_id,
+            terminalInput(reason)
+          );
+          terminal = await terminalAction;
+          return terminal;
+        }
+      };
+      let completion;
+      try {
+        completion = await callback(scope);
+        if (terminalAction) return await terminalAction;
+        if (terminal) return terminal;
+        if (!completion || typeof completion !== "object") {
+          throw new CompletionMissingError(
+            "Interaction callback must return a completion manifest"
+          );
+        }
+      } catch (error) {
+        if (!terminalAction && !terminal) {
+          try {
+            terminal = await this.api.failInteraction(
+              interaction.interaction_id,
+              terminalInput(
+                error instanceof CompletionMissingError ? "completion_missing" : "callback_failed"
+              )
+            );
+          } catch {
+          }
+        }
+        throw error;
       }
-    });
-  }
-  observeOperation(eventType, input) {
-    const operationId = input.operationId ?? this.idFactory();
-    this.operationIDs.add(operationId);
-    return this.append(eventType, { ...input, operationId });
-  }
-  createClaim(input) {
-    if (input.sourceEventIds.length === 0 || input.operationIds.length === 0) {
-      throw new Error("claim requires at least one source event and operation");
-    }
-    this.assertKnownRefs(input.sourceEventIds, this.eventIDs, "event");
-    this.assertKnownRefs(input.operationIds, this.operationIDs, "operation");
-    const event = this.append("claim.created", {
-      operationName: input.operationName,
-      causationEventId: input.causationEventId,
-      claimId: input.claimId,
-      payload: {
-        claim_id: input.claimId,
-        claim_type: input.claimType,
-        claim_hash: input.claimHash,
-        source_event_ids: input.sourceEventIds,
-        operation_ids: input.operationIds,
-        visibility: input.visibility ?? "visible",
-        version_status: input.versionStatus ?? "unversioned",
-        ...input.resultArtifactRef ? { result_artifact_ref: input.resultArtifactRef } : {}
+      const completionInput = {
+        ...completion,
+        terminal_idempotency_key: this.idFactory(),
+        lease_token: interaction.lease_token,
+        lease_epoch: interaction.lease_epoch,
+        expected_operations: completion.expected_operations ?? expectedOperations(receipts.values()),
+        expected_receipts: completion.expected_receipts ?? expectedReceipts(receipts.values())
+      };
+      try {
+        return await this.api.completeInteraction(interaction.interaction_id, completionInput);
+      } catch (completeError) {
+        let current;
+        try {
+          current = await this.api.getInteraction(interaction.interaction_id);
+        } catch {
+          throw completeError;
+        }
+        if (current.execution_status === "completed") return current;
+        if (current.execution_status !== "active") {
+          throw new InputError(
+            `Interaction terminal state "${current.execution_status}" conflicts with complete`
+          );
+        }
+        return await this.api.completeInteraction(interaction.interaction_id, completionInput);
       }
+    } finally {
+      this.activeConversationIds.delete(conversation.conversation_id);
+    }
+  }
+  async resolveConversation(strategy) {
+    switch (strategy.mode) {
+      case "resume_by_id":
+        return await this.api.resumeConversation({ conversation_id: strategy.conversationId });
+      case "create_new_generation":
+        return await this.api.createNewConversationGeneration({
+          external_conversation_key: strategy.externalConversationKey,
+          idempotency_key: this.idFactory()
+        });
+      case "one_shot":
+        return await this.api.ensureConversation({
+          external_conversation_key: strategy.externalConversationKey ?? `one-shot-${this.idFactory()}`,
+          idempotency_key: this.idFactory(),
+          one_shot: true
+        });
+      case "ensure_current":
+        return await this.ensureCurrent(strategy.externalConversationKey);
+    }
+  }
+  async ensureCurrent(externalConversationKey) {
+    const pending = this.pendingConversations.get(externalConversationKey);
+    if (pending) return await pending;
+    const request2 = this.api.ensureConversation({
+      external_conversation_key: externalConversationKey,
+      idempotency_key: this.idFactory()
     });
-    this.claimEventIDs.set(input.claimId, event.event_id);
-    return event;
-  }
-  createEvidenceRefs(input) {
-    const claimEventID = this.requireClaim(input.claimId);
-    if (input.refs.length === 0) throw new Error("evidence refs must not be empty");
-    const operationId = this.idFactory();
-    this.operationIDs.add(operationId);
-    const event = this.append("evidence.refs.created", {
-      operationName: input.operationName,
-      operationId,
-      causationEventId: input.causationEventId ?? claimEventID,
-      claimId: input.claimId,
-      payload: {
-        claim_id: input.claimId,
-        evidence_refs: input.refs.map((ref) => ({
-          ref_id: ref.refId,
-          ref_type: ref.refType,
-          source_system: ref.sourceSystem,
-          validity: ref.validity,
-          version_status: ref.versionStatus,
-          visibility: ref.visibility,
-          ...ref.summaryHash ? { summary_hash: ref.summaryHash } : {}
-        }))
+    this.pendingConversations.set(externalConversationKey, request2);
+    try {
+      return await request2;
+    } finally {
+      if (this.pendingConversations.get(externalConversationKey) === request2) {
+        this.pendingConversations.delete(externalConversationKey);
       }
-    });
-    this.claimEventIDs.set(input.claimId, event.event_id);
-    return event;
-  }
-  resolveBusinessRefs(input) {
-    const claimEventID = this.requireClaim(input.claimId);
-    if (input.resolverStatus === "resolved" && input.refs.length === 0) {
-      throw new Error("resolved business refs must not be empty");
-    }
-    const operationId = this.idFactory();
-    this.operationIDs.add(operationId);
-    const event = this.append("business.refs.resolved", {
-      operationName: input.operationName,
-      operationId,
-      causationEventId: input.causationEventId ?? claimEventID,
-      claimId: input.claimId,
-      payload: {
-        claim_id: input.claimId,
-        resolver_status: input.resolverStatus,
-        business_refs: input.refs.map((ref) => ({
-          ref_id: ref.refId,
-          ref_type: ref.refType,
-          source_system: ref.sourceSystem,
-          validity: ref.validity,
-          version_status: ref.versionStatus,
-          visibility: ref.visibility
-        }))
+    }
+  }
+  async runOperation(conversation, interaction, input, execute, bknContext, recordReceipt) {
+    const operationKey = input.operationKey ?? this.idFactory();
+    let current = await this.api.ensureOperation(
+      conversation.conversation_id,
+      interaction.interaction_id,
+      {
+        operation_key: operationKey,
+        tool_name: input.toolName,
+        normalized_input_hash: input.normalizedInputHash,
+        parent_operation_id: input.parentOperationId,
+        causation_event_ids: input.causationEventIds,
+        required: input.required ?? true,
+        lease_token: interaction.lease_token,
+        lease_epoch: interaction.lease_epoch
       }
-    });
-    this.claimEventIDs.set(input.claimId, event.event_id);
-    return event;
-  }
-  recommendAction(input) {
-    const claimEventID = this.requireClaim(input.claimId);
-    if (input.targetRefs.length === 0) throw new Error("action target refs must not be empty");
-    const operationId = this.idFactory();
-    const actionInstanceId = this.idFactory();
-    this.operationIDs.add(operationId);
-    const event = this.append("action.recommended", {
-      operationName: input.operationName,
-      operationId,
-      causationEventId: input.causationEventId ?? claimEventID,
-      claimId: input.claimId,
-      payload: {
-        action_instance_id: actionInstanceId,
-        action_type: input.actionType,
-        target_refs: input.targetRefs,
-        reason_hash: input.reasonHash,
-        ...input.reasonArtifactRef ? { reason_artifact_ref: input.reasonArtifactRef } : {},
-        ...input.inputArtifactRef ? { input_artifact_ref: input.inputArtifactRef } : {},
-        status: "recommended"
+    );
+    const maxAttempts = input.maxAttempts ?? 2;
+    if (!Number.isInteger(maxAttempts) || maxAttempts < 1 || maxAttempts > 10) {
+      throw new InputError("maxAttempts must be an integer between 1 and 10");
+    }
+    while (true) {
+      if (isCompletedReceipt(current.receipt)) {
+        recordReceipt(current.receipt);
+        return { value: void 0, receipt: current.receipt, recovered: true };
       }
-    });
-    const internal = {
-      actionInstanceId,
-      claimId: input.claimId,
-      operationId,
-      lastEventId: event.event_id,
-      state: "recommended"
-    };
-    const handle = Object.freeze({
-      get actionInstanceId() {
-        return internal.actionInstanceId;
-      },
-      get claimId() {
-        return internal.claimId;
-      },
-      get operationId() {
-        return internal.operationId;
-      },
-      get lastEventId() {
-        return internal.lastEventId;
-      },
-      get state() {
-        return internal.state;
+      if (isFailedReceipt(current.receipt)) {
+        recordReceipt(current.receipt);
+        if (!current.operation.retryable) {
+          throw new OperationFailedError(
+            `Operation "${current.operation.operation_id}" failed and is not retryable`
+          );
+        }
+        if (current.operation.attempt >= maxAttempts) {
+          throw new OperationFailedError(
+            `Operation "${current.operation.operation_id}" reached maximum attempt count ${maxAttempts}`
+          );
+        }
+        current = await this.api.retryOperationAttempt(current.operation.operation_id, {
+          lease_token: interaction.lease_token,
+          lease_epoch: interaction.lease_epoch
+        });
+        continue;
       }
-    });
-    this.actions.set(handle, internal);
-    return handle;
-  }
-  requestActionApproval(action, input) {
-    const internal = this.expectActionState(action, "recommended");
-    const event = this.appendAction(internal, "action.approval_requested", {
-      action_instance_id: internal.actionInstanceId,
-      policy_ref: input.policyRef,
-      status: "approval_requested"
-    });
-    internal.state = "approval_requested";
-    internal.lastEventId = event.event_id;
-    return event;
-  }
-  approveAction(action, input) {
-    const internal = this.expectActionState(action, "approval_requested");
-    const event = this.appendAction(internal, "action.approved", {
-      action_instance_id: internal.actionInstanceId,
-      actor_ref: input.actorRef,
-      policy_decision_ref: input.policyDecisionRef,
-      status: "approved"
-    });
-    internal.state = "approved";
-    internal.lastEventId = event.event_id;
-    return event;
-  }
-  rejectAction(action, input) {
-    const internal = this.expectActionState(action, "approval_requested");
-    const event = this.appendAction(internal, "action.rejected", {
-      action_instance_id: internal.actionInstanceId,
-      actor_ref: input.actorRef,
-      policy_decision_ref: input.policyDecisionRef,
-      status: "rejected"
-    });
-    internal.state = "rejected";
-    internal.lastEventId = event.event_id;
-    return event;
-  }
-  executeAction(action, input) {
-    const internal = this.expectActionState(
-      action,
-      "approved",
-      "requires approval before execution"
-    );
-    const event = this.appendAction(internal, "action.executed", {
-      action_instance_id: internal.actionInstanceId,
-      status: input.status,
-      invocation_ref: input.invocationRef,
-      ...input.status === "error" ? { error_category: input.errorCategory, error_hash: input.errorHash } : {}
-    });
-    internal.state = "executed";
-    internal.lastEventId = event.event_id;
-    return event;
-  }
-  recordActionResult(action, input) {
-    const internal = this.expectActionState(action, "executed");
-    const event = this.appendAction(internal, "action.result_recorded", {
-      action_instance_id: internal.actionInstanceId,
-      result_hash: input.resultHash,
-      status: input.status,
-      ...input.taskRef ? { task_ref: input.taskRef } : {},
-      ...input.artifactRef ? { artifact_ref: input.artifactRef } : {},
-      ...input.resultArtifactRef ? { result_artifact_ref: input.resultArtifactRef } : {}
-    });
-    internal.state = "result_recorded";
-    internal.lastEventId = event.event_id;
-    return event;
-  }
-  pendingEvents() {
-    return clone(this.events);
-  }
-  flush() {
-    const requestedIDs = new Set(this.events.map((event) => event.event_id));
-    const operation = this.flushTail.then(() => this.flushEvents(requestedIDs));
-    this.flushTail = operation.then(
-      () => void 0,
-      () => void 0
-    );
-    return operation;
-  }
-  appendAction(action, eventType, payload) {
-    return this.append(eventType, {
-      operationName: eventType,
-      operationId: action.operationId,
-      causationEventId: action.lastEventId,
-      claimId: action.claimId,
-      payload
-    });
-  }
-  append(eventType, input) {
-    assertSafePayload(eventType, input.payload);
-    this.assertContractPayload(eventType, input.payload);
-    if (eventType !== "agent.interaction.started") {
-      if (!input.causationEventId) throw new Error(`${eventType} requires causation_event_id`);
-      if (!this.eventIDs.has(input.causationEventId)) {
-        throw new Error(`unknown event reference: ${input.causationEventId}`);
+      let result;
+      try {
+        result = await execute({
+          context: bknContext(operationKey, input.parentOperationId, input.causationEventIds),
+          operation: current.operation,
+          receipt: current.receipt
+        });
+      } catch (executeError) {
+        const recovered = await this.api.getReceipt(current.receipt.receipt_id);
+        if (!isTerminalReceipt(recovered)) throw executeError;
+        assertSameReceipt(current.receipt, recovered);
+        current = {
+          ...current,
+          operation: isFailedReceipt(recovered) ? await this.api.getOperation(current.operation.operation_id) : current.operation,
+          receipt: recovered
+        };
+        continue;
       }
-    }
-    if (eventType !== "agent.interaction.started" && eventType !== "claim.created" && !input.operationId) {
-      throw new Error(`${eventType} requires operation_id`);
-    }
-    const eventID = this.idFactory();
-    if (this.eventIDs.has(eventID)) throw new Error(`duplicate event id: ${eventID}`);
-    const timestamp = this.now();
-    const event = {
-      event_id: eventID,
-      event_type: eventType,
-      "bkn.trace.schema.version": this.contractVersion,
-      observed_at: timestamp,
-      emitted_at: timestamp,
-      producer_module: this.producerModule,
-      trace_id: this.trace.trace_id,
-      span_id: this.spanId,
-      "bkn.request.id": this.trace["bkn.request.id"],
-      "bkn.operation.name": input.operationName,
-      interaction_id: this.interactionId,
-      ...input.operationId ? { operation_id: input.operationId } : {},
-      ...input.causationEventId ? { causation_event_id: input.causationEventId } : {},
-      ...input.claimId ? { claim_id: input.claimId } : {},
-      ...input.attempt ? { attempt: input.attempt } : {},
-      payload: clone(input.payload)
-    };
-    this.events.push(clone(event));
-    this.eventIDs.add(eventID);
-    return clone(event);
-  }
-  async flushEvents(requestedIDs) {
-    const batch = this.events.filter((event) => requestedIDs.has(event.event_id));
-    if (batch.length === 0) return void 0;
-    const response = await this.emit({
-      "bkn.trace.schema.version": this.contractVersion,
-      trace: clone(this.trace),
-      events: clone(batch)
-    });
-    const remaining = this.events.filter((event) => !requestedIDs.has(event.event_id));
-    this.events.splice(0, this.events.length, ...remaining);
-    return response;
-  }
-  assertContractPayload(eventType, payload) {
-    if (this.contractVersion !== "2.2.0") return;
-    const requiredArtifactFields = {
-      "agent.interaction.started": ["question_artifact_ref"],
-      "data.query.observed": ["query_artifact_ref", "result_artifact_ref"],
-      "logic.execution.observed": ["input_artifact_ref", "result_artifact_ref"],
-      "claim.created": ["result_artifact_ref"],
-      "action.recommended": ["input_artifact_ref"],
-      "action.result_recorded": ["result_artifact_ref"]
-    };
-    for (const field of requiredArtifactFields[eventType] ?? []) {
-      const value = payload[field];
-      if (typeof value !== "string" || !/^artifact:[0-9A-Za-z][0-9A-Za-z_.:-]{0,127}$/.test(value)) {
-        throw new Error(`${eventType} payload requires valid ${field}`);
+      assertSameReceipt(current.receipt, result.receipt);
+      recordReceipt(result.receipt);
+      if (isCompletedReceipt(result.receipt)) {
+        return { ...result, recovered: false };
       }
-    }
-    for (const [field, value] of Object.entries(payload)) {
-      if (field.endsWith("_artifact_ref") && value !== void 0) {
-        if (typeof value !== "string" || !/^artifact:[0-9A-Za-z][0-9A-Za-z_.:-]{0,127}$/.test(value)) {
-          throw new Error(`${eventType} payload requires valid ${field}`);
-        }
+      current = {
+        ...current,
+        operation: isFailedReceipt(result.receipt) ? await this.api.getOperation(current.operation.operation_id) : current.operation,
+        receipt: result.receipt
+      };
+      if (!isTerminalReceipt(result.receipt)) {
+        throw new InputError(
+          `Operation "${current.operation.operation_id}" returned a pending receipt`
+        );
       }
     }
-    if (eventType === "action.result_recorded" && payload.artifact_ref !== void 0) {
-      throw new Error("action.result_recorded 2.2 does not accept legacy artifact_ref");
-    }
   }
-  assertKnownRefs(values, known, kind) {
-    for (const value of values) {
-      if (!known.has(value)) throw new Error(`unknown ${kind} reference: ${value}`);
-    }
+};
+function assertSafeStrategy(strategy) {
+  if (!strategy || typeof strategy !== "object") {
+    throw new InputError("A conversation strategy is required");
   }
-  requireClaim(claimID) {
-    const eventID = this.claimEventIDs.get(claimID);
-    if (!eventID) throw new Error(`unknown claim reference: ${claimID}`);
-    return eventID;
+  for (const field of FORBIDDEN_INPUT_FIELDS2) {
+    if (field in strategy) throw new InputError(`Lifecycle input field "${field}" is not allowed`);
   }
-  expectActionState(action, expected, message) {
-    const internal = this.actions.get(action);
-    if (!internal) throw new Error("action handle does not belong to this trace session");
-    if (internal.state !== expected) {
-      if (message) throw new Error(`action ${internal.actionInstanceId} ${message}`);
-      throw new Error(
-        `action ${internal.actionInstanceId} must be ${expected}, got ${internal.state}`
-      );
-    }
-    return internal;
+}
+function expectedOperations(receipts) {
+  const operations = /* @__PURE__ */ new Map();
+  for (const receipt of receipts) {
+    operations.set(
+      receipt.operation_id,
+      (operations.get(receipt.operation_id) ?? false) || receipt.required
+    );
   }
-};
+  return [...operations].map(([operation_id, required]) => ({ operation_id, required }));
+}
+function expectedReceipts(receipts) {
+  return [...receipts].map((receipt) => ({
+    receipt_id: receipt.receipt_id,
+    required: receipt.required
+  }));
+}
+function isTerminalReceipt(receipt) {
+  return receipt.receipt_status !== "pending";
+}
+function isCompletedReceipt(receipt) {
+  return receipt.receipt_status === "completed";
+}
+function isFailedReceipt(receipt) {
+  return receipt.receipt_status === "failed";
+}
+function assertSameReceipt(expected, actual) {
+  if (actual.receipt_id !== expected.receipt_id || actual.operation_id !== expected.operation_id || actual.attempt !== expected.attempt || actual.operation_key !== expected.operation_key || actual.normalized_input_hash !== expected.normalized_input_hash) {
+    throw new InputError("Recovered receipt does not match the registered operation attempt");
+  }
+}
 
 // src/api/trace.ts
 var SEARCH = "/api/agent-observability/v1/traces/_search";
-var EVIDENCE_EVENTS = "/api/agent-observability/v1/evidence/events";
-var EVIDENCE_ARTIFACTS = "/api/agent-observability/v1/evidence/artifacts";
-var REQUESTS = "/api/agent-observability/v1/requests";
-var INTERACTIONS = "/api/agent-observability/v1/interactions";
+var BUSINESS_PROVENANCE = "/api/agent-observability/v1/business-provenance";
+var REQUESTS = `${BUSINESS_PROVENANCE}/requests`;
+var INTERACTIONS = `${BUSINESS_PROVENANCE}/interactions`;
 var TRACES = "/api/agent-observability/v1/traces";
 function isoToNanos(iso) {
   const ms = Date.parse(iso);
@@ -5339,67 +5724,9 @@ async function getRawSpansByConversation(ctx, conversationId, opts = {}) {
 function traceSearch(ctx, body) {
   return request(ctx, SEARCH, { method: "POST", body });
 }
-function emitEvidenceEvents(ctx, body) {
-  return request(ctx, EVIDENCE_EVENTS, {
-    method: "POST",
-    body,
-    headers: evidenceWriteHeaders(ctx),
-    redirect: "manual"
-  });
-}
-function emitEvidenceArtifact(ctx, body) {
-  return request(ctx, EVIDENCE_ARTIFACTS, {
-    method: "POST",
-    body,
-    headers: evidenceWriteHeaders(ctx),
-    redirect: "manual"
-  });
-}
-function evidenceWriteHeaders(ctx) {
-  return ctx.evidenceIngestToken ? { "x-bkn-trace-ingest-token": ctx.evidenceIngestToken } : void 0;
-}
-function getEvidenceArtifact(ctx, artifactId) {
-  return request(ctx, `${EVIDENCE_ARTIFACTS}/${encodeURIComponent(artifactId)}`);
-}
-function listRequestSummaries(ctx, query = {}) {
-  return request(ctx, REQUESTS, {
-    query: summaryQuery(query)
-  });
-}
-function getRequestSummary(ctx, requestId) {
-  return request(ctx, `${REQUESTS}/${encodeURIComponent(requestId)}`);
-}
-function getInteractionSummary(ctx, interactionId) {
-  return request(ctx, `${INTERACTIONS}/${encodeURIComponent(interactionId)}`);
-}
-function getRequestTraces(ctx, requestId, query = {}) {
-  return request(
-    ctx,
-    `${REQUESTS}/${encodeURIComponent(requestId)}/traces`,
-    { query: summaryQuery(query) }
-  );
-}
 function getTraceGraph(ctx, traceId) {
   return request(ctx, `${TRACES}/${encodeURIComponent(traceId)}/trace-graph`);
 }
-function getEvidenceChain(ctx, scope, opts = {}) {
-  const target = traceTarget(scope, "evidence-chain");
-  return request(ctx, target.path, {
-    query: queryWithLimit(target.query, opts)
-  });
-}
-function getBusinessGraph(ctx, scope, opts = {}) {
-  const target = traceTarget(scope, "business-graph");
-  return request(ctx, target.path, {
-    query: queryWithLimit(target.query, opts)
-  });
-}
-function getSnapshotPreview(ctx, scope, opts = {}) {
-  const target = traceTarget(scope, "snapshot-preview");
-  return request(ctx, target.path, {
-    query: queryWithLimit(target.query, opts)
-  });
-}
 async function getSpansByConversation(ctx, conversationId, opts = {}) {
   const agg = await request(ctx, SEARCH, {
     method: "POST",
@@ -5424,38 +5751,6 @@ async function getSpansByConversation(ctx, conversationId, opts = {}) {
   }) ?? {};
   return (spans.hits?.hits ?? []).map((h) => h._source ?? {});
 }
-function traceTarget(scope, subresource) {
-  if (typeof scope === "string") {
-    return { path: `${TRACES}/${encodeURIComponent(scope)}/${subresource}` };
-  }
-  if ("traceId" in scope) {
-    return { path: `${TRACES}/${encodeURIComponent(scope.traceId)}/${subresource}` };
-  }
-  const requestPath = subresource === "evidence-chain" ? `${TRACES}/by-request` : `${TRACES}/by-request/${subresource}`;
-  return { path: requestPath, query: { request_id: scope.requestId } };
-}
-function queryWithLimit(query, opts) {
-  if (opts.limit === void 0 || !Number.isFinite(opts.limit)) return query;
-  return { ...query ?? {}, limit: opts.limit };
-}
-function summaryQuery(query) {
-  const result = {};
-  if (query.limit !== void 0 && Number.isFinite(query.limit)) result.limit = query.limit;
-  if (query.cursor) result.cursor = query.cursor;
-  if (query.from) result.from = query.from;
-  if (query.to) result.to = query.to;
-  if (query.status) result.status = query.status;
-  if (query.agentOrApp) result.agent_or_app = query.agentOrApp;
-  if (query.businessDomain) result.business_domain = query.businessDomain;
-  if (query.conversationId) result.conversation_id = query.conversationId;
-  if (query.interactionId) result.interaction_id = query.interactionId;
-  if (query.knowledgeNetwork) result.knowledge_network = query.knowledgeNetwork;
-  if (query.evidenceCompleteness) {
-    result.evidence_completeness = query.evidenceCompleteness;
-  }
-  if (query.keyword) result.keyword = query.keyword;
-  return Object.keys(result).length ? result : void 0;
-}
 
 // src/bkn-trace/claude-judge.ts
 import { spawn as spawn2, spawnSync as spawnSync2 } from "child_process";
@@ -6838,6 +7133,8 @@ async function semanticJudge(question, answer, reference) {
   };
 }
 function trace(ctx) {
+  const lifecycle = traceLifecycleApi(ctx);
+  const managed = new ManagedTrace(lifecycle);
   const diagnoseOne = async (conversationId, opts = {}) => {
     const { spans, traceIds } = await getRawSpansByConversation(ctx, conversationId);
     if (spans.length === 0) throw new Error(`No spans found for conversation: ${conversationId}`);
@@ -6866,34 +7163,14 @@ function trace(ctx) {
     };
   };
   return {
+    /** Low-level BKN Trace 3.0 lifecycle and durable receipt API. */
+    lifecycle,
+    /** Own one complete interaction lifecycle around an application callback. */
+    withInteraction: managed.withInteraction.bind(managed),
     /** Raw trace search (OpenSearch-style body). */
     search: (body) => traceSearch(ctx, body),
-    /** Submit BKN Trace phase-two claim/evidence/business events. */
-    emitEvidenceEvents: (body) => emitEvidenceEvents(ctx, body),
-    /** Store one authorized BKN Trace 2.2 business-content artifact. */
-    emitArtifact: (body) => emitEvidenceArtifact(ctx, body),
-    /** Read one authorized BKN Trace 2.2 business-content artifact. */
-    artifact: (artifactId) => getEvidenceArtifact(ctx, artifactId),
-    /** Product-facing business request list and request-to-trace drilldown. */
-    requests: {
-      get: (requestId) => getRequestSummary(ctx, requestId),
-      list: (query) => listRequestSummaries(ctx, query),
-      traces: (requestId, query) => getRequestTraces(ctx, requestId, query)
-    },
-    /** Aggregate all OpenBKN requests and traces for one caller-owned interaction. */
-    interactions: {
-      get: (interactionId) => getInteractionSummary(ctx, interactionId)
-    },
-    /** Create a typed BKN Trace 2.1 session for an Agent or AI application. */
-    createSession: (options) => new TraceSession({ ...options, emit: (body) => emitEvidenceEvents(ctx, body) }),
     /** Normalized trace tree/status graph by trace id. */
     graph: (traceId) => getTraceGraph(ctx, traceId),
-    /** Claim -> evidence/business refs graph by trace id or BKN request id. */
-    evidenceChain: (scope, opts) => getEvidenceChain(ctx, scope, opts),
-    /** Business semantic graph by trace id or BKN request id. */
-    businessGraph: (scope, opts) => getBusinessGraph(ctx, scope, opts),
-    /** Metadata-only evidence snapshot preview by trace id or BKN request id. */
-    snapshotPreview: (scope, opts) => getSnapshotPreview(ctx, scope, opts),
     /** All span source docs for a conversation. */
     spans: (conversationId, opts) => getSpansByConversation(ctx, conversationId, opts),
     diagnose: diagnoseOne,
@@ -6965,15 +7242,18 @@ function vega(ctx) {
   return {
     catalogs: (opts) => listCatalogs(ctx, opts),
     getCatalog: (id) => getCatalog(ctx, id),
-    createCatalog: (req) => createCatalog(ctx, req),
-    updateCatalog: (id, req) => updateCatalog(ctx, id, req),
+    createCatalog: (req, opts) => createCatalog(ctx, req, opts),
+    updateCatalog: (id, req, opts) => updateCatalog(ctx, id, req, opts),
     enableCatalog: (id) => enableCatalog(ctx, id),
     disableCatalog: (id) => disableCatalog(ctx, id),
     deleteCatalog: (id) => deleteCatalog(ctx, id),
+    testCatalogConnectionConfig: (req) => testCatalogConnectionConfig(ctx, req),
     testCatalogConnection: (id) => testCatalogConnection(ctx, id),
+    catalogHealthCheckSchedule: (id) => getCatalogHealthCheckSchedule(ctx, id),
+    updateCatalogHealthCheckSchedule: (id, req) => updateCatalogHealthCheckSchedule(ctx, id, req),
     discoverCatalog: (id, wait = false) => discoverCatalog(ctx, id, wait),
     catalogResources: (id, category, limit, offset) => listCatalogResources(ctx, id, category, limit, offset),
-    catalogHealth: (ids) => catalogHealthStatus(ctx, ids),
+    catalogHealth: (id) => catalogHealthStatus(ctx, id),
     connectorTypes: () => listConnectorTypes(ctx),
     connectorType: (type) => getConnectorType(ctx, type),
     /** Run SQL / OpenSearch DSL directly against a data source. */
@@ -7120,7 +7400,7 @@ function createClient(opts = {}) {
     kn: kn(ctx),
     resource: resources(ctx),
     dataflows: dataflows(ctx),
-    agents: agents(ctx),
+    agents: agents2(ctx),
     context: context(ctx),
     models: models(ctx),
     skills: skills(ctx),
@@ -7158,7 +7438,7 @@ function hostOf(baseUrl) {
     return baseUrl;
   }
 }
-function normalize(baseUrl) {
+function normalize2(baseUrl) {
   return baseUrl.replace(/\/+$/, "");
 }
 function usernameOf(token) {
@@ -7167,7 +7447,7 @@ function usernameOf(token) {
   return token.username ?? token.displayName ?? claims?.preferred_username ?? claims?.name ?? claims?.sub;
 }
 function attachToken(baseUrl, accessToken, opts = {}) {
-  const url = normalize(baseUrl);
+  const url = normalize2(baseUrl);
   const token = {
     baseUrl: url,
     accessToken,
@@ -7270,7 +7550,7 @@ function listPlatforms2() {
   );
 }
 function use(baseUrl) {
-  const url = normalize(baseUrl);
+  const url = normalize2(baseUrl);
   if (!readToken(url)) {
     throw new InputError(`No saved credentials for ${url}. Run \`openbkn auth login\` first.`);
   }
@@ -7281,10 +7561,10 @@ function logout() {
   return baseUrl ? deleteToken(baseUrl) : false;
 }
 function deletePlatform(baseUrl, userId) {
-  return deleteToken(normalize(baseUrl), userId);
+  return deleteToken(normalize2(baseUrl), userId);
 }
 function switchUser(baseUrl, userOrName) {
-  const url = normalize(baseUrl);
+  const url = normalize2(baseUrl);
   const users = usersOf(url);
   const match = users.find((u) => u.userId === userOrName) ?? users.find((u) => (u.username ?? u.displayName) === userOrName);
   if (!match) {
@@ -7295,7 +7575,7 @@ function switchUser(baseUrl, userOrName) {
   return { baseUrl: url, userId: match.userId, username: match.username ?? match.displayName };
 }
 function usersOf(baseUrl) {
-  const url = normalize(baseUrl);
+  const url = normalize2(baseUrl);
   return listPlatforms().find((p) => p.baseUrl === url)?.users ?? [];
 }
 function exportCreds() {
@@ -7313,6 +7593,7 @@ function exportCreds() {
 
 export {
   HttpError,
+  ToolError,
   InputError,
   toExitCode,
   formatError,
@@ -7321,6 +7602,7 @@ export {
   deviceLogin,
   credentialDeviceLogin,
   request,
+  lifecycleHint,
   rawCall,
   DEFAULT_BUSINESS_DOMAIN,
   DEFAULT_LIST_LIMIT,
@@ -7334,7 +7616,8 @@ export {
   getUserSafe,
   changePasswordSafe,
   admin,
-  agents,
+  agents2 as agents,
+  releaseLifecycleSessions,
   context,
   dataflows,
   parsePkMap,
@@ -7342,11 +7625,15 @@ export {
   kn,
   models,
   resources,
+  classifyPath,
+  filesUnder,
+  renderTree,
   skills,
   toolboxes,
+  traceLifecycleApi,
   renderReportMarkdown,
   validateFixturePath,
-  TraceSession,
+  ManagedTrace,
   trace,
   vega,
   createClient,
@@ -7363,4 +7650,4 @@ export {
   exportCreds,
   auth_exports
 };
-//# sourceMappingURL=chunk-LH3ONZGQ.js.map
+//# sourceMappingURL=chunk-PC2F54XD.js.map