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

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

@@ -20,44 +20,53 @@ 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);
     this.name = "InputError";
   }
 };
-function toExitCode(err) {
-  if (err instanceof InputError) return 2;
-  if (err instanceof HttpError) {
-    if (err.status === 401 || err.status === 403) return 3;
+function toExitCode(err2) {
+  if (err2 instanceof InputError) return 2;
+  if (err2 instanceof HttpError) {
+    if (err2.status === 401 || err2.status === 403) return 3;
     return 1;
   }
   return 1;
 }
-function formatError(err) {
-  if (err instanceof HttpError) {
-    const serverMsg = serverError(err.body);
-    if (err.status === 401) {
-      const next = err.hint ?? "Run `openbkn auth login` and retry.";
-      return `Not authorized (HTTP 401)${serverMsg ? `: ${serverMsg}` : ""}. ${next}`;
+function formatError(err2) {
+  if (err2 instanceof HttpError) {
+    const serverMsg = serverError(err2.body);
+    if (err2.status === 401) {
+      const next2 = err2.hint ?? "Run `openbkn auth login` and retry.";
+      return `Not authorized (HTTP 401)${serverMsg ? `: ${serverMsg}` : ""}. ${next2}`;
     }
-    if (err.status === 403) {
+    if (err2.status === 403) {
       return `Forbidden (HTTP 403)${serverMsg ? `: ${serverMsg}` : " \u2014 admin privileges required"}.`;
     }
-    const detail = err.body ? `: ${truncate(err.body, 500)}` : "";
-    return `Request failed (HTTP ${err.status} ${err.statusText})${detail}`;
+    const detail = err2.body ? `: ${truncate(err2.body, 500)}` : "";
+    const next = err2.hint ? ` ${err2.hint}` : "";
+    return `Request failed (HTTP ${err2.status} ${err2.statusText})${detail}${next}`;
   }
-  if (err instanceof Error) {
-    const cause = err.cause;
+  if (err2 instanceof Error) {
+    const cause = err2.cause;
     if (cause?.code && isTlsCertError(cause.code)) {
       return `TLS certificate rejected (${cause.code}). The platform is likely self-signed \u2014 retry with \`-k\`/\`--insecure\`.`;
     }
-    if (err.message === "fetch failed" && cause?.message) {
+    if (err2.message === "fetch failed" && cause?.message) {
       return `Request failed: ${cause.message}${cause.code ? ` (${cause.code})` : ""}`;
     }
-    return err.message;
+    return err2.message;
   }
-  return String(err);
+  return String(err2);
 }
 function serverError(body) {
   if (!body) return "";
@@ -80,17 +89,44 @@ function truncate(s, n) {
 import { spawn } from "child_process";
 
 // src/api/tls.ts
-import { Agent, fetch as undiciFetch } from "undici";
-var insecureAgent;
-function insecureDispatcher() {
-  insecureAgent ??= new Agent({ connect: { rejectUnauthorized: false } });
-  return insecureAgent;
-}
-function tlsFetch(insecure, url, init) {
-  if (!insecure) return fetch(url, init);
+import { Agent, FormData as UndiciFormData, fetch as undiciFetch } from "undici";
+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";
+}
+function toUndiciBody(body) {
+  if (body instanceof UndiciFormData || !isFormData(body)) return body;
+  const form2 = new UndiciFormData();
+  for (const [name, value] of body.entries()) {
+    if (typeof value === "string") form2.append(name, value);
+    else form2.append(name, value, value.name);
+  }
+  return form2;
+}
+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,
-    dispatcher: insecureDispatcher()
+    ...init?.body === void 0 || init?.body === null ? {} : { body: toUndiciBody(init.body) },
+    dispatcher: dispatcherFor(insecure === true, needsAgent ? headersTimeoutMs : void 0)
   });
 }
 
@@ -305,11 +341,96 @@ async function credentialDeviceLogin(baseUrl, username, password, opts = {}) {
   );
 }
 
+// src/trace-context.ts
+import { randomBytes, randomUUID } from "crypto";
+var TRACEPARENT_RE = /^00-([0-9a-f]{32})-([0-9a-f]{16})-[0-9a-f]{2}$/;
+var REQUEST_ID_RE = /^req_[0-9A-Za-z_.-]+$/;
+var CORRELATION_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+var RFC3339_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2})$/;
+var ALLOWED_BAGGAGE = /* @__PURE__ */ new Set(["bkn.account.type", "bkn.runtime.env"]);
+function isValidRequestId(value) {
+  return typeof value === "string" && REQUEST_ID_RE.test(value);
+}
+function isValidCorrelationId(value) {
+  return typeof value === "string" && CORRELATION_ID_RE.test(value.trim());
+}
+function isValidTraceparent(value) {
+  if (typeof value !== "string") return false;
+  const match = TRACEPARENT_RE.exec(value);
+  if (!match) return false;
+  const [, traceId, spanId] = match;
+  return traceId !== "0".repeat(32) && spanId !== "0".repeat(16);
+}
+function createTraceContext(opts = {}) {
+  const requestId = isValidRequestId(opts.requestId) ? opts.requestId : `req_${randomUUID()}`;
+  const traceparent = isValidTraceparent(opts.traceparent) ? opts.traceparent : newTraceparent();
+  const baggage = filterBaggage(opts.baggage);
+  const conversationId = isValidCorrelationId(opts.conversationId) ? opts.conversationId.trim() : void 0;
+  const interactionId = isValidCorrelationId(opts.interactionId) ? opts.interactionId.trim() : void 0;
+  const operationId = isValidCorrelationId(opts.operationId) ? opts.operationId.trim() : void 0;
+  const attempt = Number.isInteger(opts.attempt) && (opts.attempt ?? 0) >= 1 && (opts.attempt ?? 0) <= 1e3 ? opts.attempt : void 0;
+  const observedAt = isValidObservedAt(opts.observedAt) ? opts.observedAt : void 0;
+  return {
+    requestId,
+    traceparent,
+    ...conversationId ? { conversationId } : {},
+    ...interactionId ? { interactionId } : {},
+    ...operationId ? { operationId } : {},
+    ...attempt ? { attempt } : {},
+    ...observedAt ? { observedAt } : {},
+    ...Object.keys(baggage).length > 0 ? { baggage } : {}
+  };
+}
+function createOperationTraceContext(trace2) {
+  return {
+    ...trace2,
+    operationId: trace2.operationId ?? `op_${randomUUID()}`,
+    attempt: trace2.attempt ?? 1,
+    observedAt: isValidObservedAt(trace2.observedAt) ? trace2.observedAt : (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function isValidObservedAt(value) {
+  return typeof value === "string" && RFC3339_RE.test(value) && !Number.isNaN(Date.parse(value));
+}
+function filterBaggage(baggage) {
+  const filtered = {};
+  for (const [key, value] of Object.entries(baggage ?? {})) {
+    if (ALLOWED_BAGGAGE.has(key) && value !== "") filtered[key] = value;
+  }
+  return filtered;
+}
+function serializeBaggage(baggage) {
+  const filtered = filterBaggage(baggage);
+  const entries = Object.entries(filtered);
+  if (entries.length === 0) return void 0;
+  return entries.map(([key, value]) => `${key}=${encodeURIComponent(value)}`).join(",");
+}
+function newTraceparent() {
+  return `00-${randomHex(16)}-${randomHex(8)}-01`;
+}
+function randomHex(bytes) {
+  let value = randomBytes(bytes).toString("hex");
+  while (/^0+$/.test(value)) value = randomBytes(bytes).toString("hex");
+  return value;
+}
+
 // src/api/headers.ts
 function buildHeaders(ctx, extra) {
+  const baggage = serializeBaggage(ctx.trace?.baggage);
   return {
     authorization: `Bearer ${ctx.token}`,
     "x-business-domain": ctx.businessDomain,
+    ...ctx.trace ? {
+      "bkn-request-id": ctx.trace.requestId,
+      "x-request-id": ctx.trace.requestId,
+      traceparent: ctx.trace.traceparent,
+      ...ctx.trace.conversationId ? { "bkn-conversation-id": ctx.trace.conversationId } : {},
+      ...ctx.trace.interactionId ? { "bkn-interaction-id": ctx.trace.interactionId } : {},
+      ...ctx.trace.operationId ? { "bkn-operation-id": ctx.trace.operationId } : {},
+      ...ctx.trace.attempt ? { "bkn-attempt": String(ctx.trace.attempt) } : {},
+      ...ctx.trace.observedAt ? { "bkn-event-observed-at": ctx.trace.observedAt } : {}
+    } : {},
+    ...baggage ? { baggage } : {},
     ...extra
   };
 }
@@ -328,32 +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,
-    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;
@@ -588,6 +736,13 @@ function resolveContext(opts = {}) {
     token,
     businessDomain: opts.businessDomain ?? readPlatformConfig(normalized).businessDomain ?? DEFAULT_BUSINESS_DOMAIN,
     insecure,
+    ...opts.evidenceIngestToken ?? process.env.BKN_TRACE_EVIDENCE_INGEST_TOKEN ? {
+      evidenceIngestToken: opts.evidenceIngestToken ?? process.env.BKN_TRACE_EVIDENCE_INGEST_TOKEN
+    } : {},
+    // Correlation ids come from `opts.trace` only. The CLI reads its flags and
+    // env vars in `commands/_shared.ts`; a library client must not inherit an
+    // ambient interaction id it would then freeze for its whole lifetime.
+    trace: createTraceContext(opts.trace),
     ...refresh ? { refresh } : {}
   };
 }
@@ -774,12 +929,12 @@ async function importLicenseSafe(ctx, licenseText, opts = {}) {
       method: "POST",
       body: { license: text }
     });
-  } catch (err) {
-    if (err instanceof HttpError) {
-      const stored = storedImport(err.body);
+  } catch (err2) {
+    if (err2 instanceof HttpError) {
+      const stored = storedImport(err2.body);
       if (stored) return stored;
     }
-    throw err;
+    throw err2;
   }
 }
 function storedImport(body) {
@@ -1088,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),
@@ -1137,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";
@@ -1150,19 +1308,20 @@ function nextId() {
 function mcpUrl(ctx) {
   return `${ctx.baseUrl}${MCP_PATH}`;
 }
+function operationContext(ctx) {
+  return ctx.trace ? { ...ctx, trace: createOperationTraceContext(ctx.trace) } : ctx;
+}
 function mcpInfo(ctx) {
   return request(ctx, `${MCP_PATH}/info`);
 }
 function headers(ctx, knId, sessionId) {
-  const h = {
+  return buildHeaders(ctx, {
     "content-type": "application/json",
     accept: "application/json, text/event-stream",
     "x-kn-id": knId,
     "mcp-protocol-version": PROTOCOL,
-    authorization: `Bearer ${ctx.token}`
-  };
-  if (sessionId) h["mcp-session-id"] = sessionId;
-  return h;
+    ...sessionId ? { "mcp-session-id": sessionId } : {}
+  });
 }
 function parseBody(text) {
   try {
@@ -1173,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}`;
@@ -1207,34 +1373,108 @@ 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 callTool(ctx, knId, name, args) {
-  const sessionId = await ensureSession(ctx, knId);
-  const { text } = await post(ctx, knId, sessionId, {
+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 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 sessionId = await ensureSession(ctx, knId);
-  const { text } = await post(ctx, knId, sessionId, {
+  const operationCtx = operationContext(ctx);
+  const sessionId = await ensureSession(operationCtx, knId);
+  const { text } = await post(operationCtx, knId, sessionId, {
     jsonrpc: "2.0",
     method,
     params: Object.keys(params).length > 0 ? params : void 0,
@@ -1297,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 {
@@ -1309,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),
@@ -1369,7 +1829,11 @@ async function executeDataflow(ctx, body, opts = {}) {
 }
 function listDataflowRuns(ctx, dagId, opts = {}) {
   return request(ctx, `${BASE2}/dag/${encodeURIComponent(dagId)}/results`, {
-    query: { since: opts.since || void 0 }
+    query: {
+      since: opts.since || void 0,
+      page: opts.page,
+      limit: opts.limit && opts.limit > 0 ? opts.limit : void 0
+    }
   });
 }
 function runDataflowRemote(ctx, dagId, url, name) {
@@ -1425,9 +1889,11 @@ function deleteKnowledgeNetwork(ctx, knId) {
 function updateKnowledgeNetwork(ctx, knId, body) {
   return request(ctx, `${ONTOLOGY_BASE}/${encodeURIComponent(knId)}`, { method: "PUT", body });
 }
+var QUERY_OVER_POST = { "X-HTTP-Method-Override": "GET" };
 function querySubgraph(ctx, knId, body) {
   return request(ctx, `${ONTOLOGY_QUERY_BASE}/${encodeURIComponent(knId)}/subgraph`, {
     method: "POST",
+    headers: QUERY_OVER_POST,
     body
   });
 }
@@ -1459,13 +1925,7 @@ function queryObjectTypeInstances(ctx, knId, otId, body) {
   return request(
     ctx,
     `${ONTOLOGY_QUERY_BASE}/${encodeURIComponent(knId)}/object-types/${encodeURIComponent(otId)}`,
-    { method: "POST", body }
-  );
-}
-function getObjectTypeProperties(ctx, knId, otId) {
-  return request(
-    ctx,
-    `${ONTOLOGY_QUERY_BASE}/${encodeURIComponent(knId)}/object-types/${encodeURIComponent(otId)}/properties`
+    { method: "POST", headers: QUERY_OVER_POST, body }
   );
 }
 function queryActionType(ctx, knId, atId, body) {
@@ -1606,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
@@ -1634,7 +2111,10 @@ function listResources2(ctx, opts = {}) {
       category: opts.category || void 0,
       status: opts.status || void 0,
       database: opts.database || void 0,
-      limit: opts.limit && opts.limit > 0 ? opts.limit : void 0,
+      // Same `/resources` endpoint as `catalogResources`: limit=-1 (NO_LIMIT)
+      // fetches every row; any other non-positive/invalid value falls back to
+      // the backend default.
+      limit: Number.isFinite(opts.limit) && (opts.limit > 0 || opts.limit === -1) ? opts.limit : void 0,
       offset: opts.offset,
       sort: opts.sort,
       direction: opts.direction,
@@ -1750,18 +2230,31 @@ function deleteResource(ctx, id, opts = {}) {
   });
 }
 async function findResource(ctx, name, opts = {}) {
-  const result = await listResources2(ctx, { name, datasourceId: opts.datasourceId });
+  const result = await listResources2(ctx, {
+    name,
+    datasourceId: opts.datasourceId,
+    limit: opts.limit
+  });
   const list = Array.isArray(result) ? result : result.entries ?? [];
   return opts.exact ? list.filter((r) => r.name === name) : list;
 }
 function queryResource(ctx, id, opts = {}) {
-  return request(ctx, `${BASE3}/${encodeURIComponent(id)}/data`, {
-    method: "POST",
-    body: {
+  const body = opts.cursor ? {
+    paging: { cursor: opts.cursor },
+    need_total: opts.needTotal ?? false
+  } : {
+    paging: {
+      mode: opts.pagingMode ?? "single",
       limit: opts.limit ?? 50,
       offset: opts.offset ?? 0,
-      need_total: opts.needTotal ?? false
-    }
+      ...opts.keepAliveSec !== void 0 ? { keep_alive_sec: opts.keepAliveSec } : {}
+    },
+    need_total: opts.needTotal ?? false
+  };
+  return request(ctx, `${BASE3}/${encodeURIComponent(id)}/data`, {
+    method: "POST",
+    headers: { "X-HTTP-Method-Override": "GET" },
+    body
   });
 }
 
@@ -2999,7 +3492,11 @@ function listBknResources(ctx) {
   return request(ctx, "/api/bkn-backend/v1/resources");
 }
 function relationTypePaths(ctx, knId, body) {
-  return request(ctx, knPath(knId, "relation-type-paths"), { method: "POST", body });
+  return request(ctx, knPath(knId, "relation-type-paths"), {
+    method: "POST",
+    headers: { "X-HTTP-Method-Override": "GET" },
+    body
+  });
 }
 function listConceptGroups(ctx, knId) {
   return request(ctx, knPath(knId, "concept-groups"));
@@ -3060,45 +3557,107 @@ function setActionScheduleStatus(ctx, knId, scheduleId, body) {
 function deleteActionSchedules(ctx, knId, ids) {
   return request(ctx, knPath(knId, `action-schedules/${ids}`), { method: "DELETE" });
 }
-function listJobs(ctx, knId) {
-  return request(ctx, knPath(knId, "jobs"));
-}
-function getJob(ctx, knId, jobId) {
-  return request(ctx, knPath(knId, `jobs/${encodeURIComponent(jobId)}`));
-}
-function getJobTasks(ctx, knId, jobId) {
-  return request(ctx, knPath(knId, `jobs/${encodeURIComponent(jobId)}/tasks`));
-}
-function deleteJobs(ctx, knId, ids) {
-  return request(ctx, knPath(knId, `jobs/${ids}`), { method: "DELETE" });
-}
 
 // src/api/vega.ts
 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 = {
@@ -3109,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,
@@ -3123,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)}`);
@@ -3173,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) {
@@ -3215,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`, {
@@ -3227,16 +3844,23 @@ function discoverCatalog(ctx, id, wait = true) {
     timeoutMs: 12e4
   });
 }
-function listCatalogResources(ctx, id, category) {
+function listCatalogResources(ctx, id, category, limit, offset) {
   return request(ctx, `${VEGA_BASE}/resources`, {
-    query: { catalog_id: id, category: category || void 0 }
+    query: {
+      catalog_id: id,
+      category: category || void 0,
+      // limit=-1 (NO_LIMIT) fetches all; NaN / 0 fall back to the backend default.
+      limit: Number.isFinite(limit) && (limit > 0 || limit === -1) ? limit : void 0,
+      offset: offset || void 0
+    }
   });
 }
-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" } });
@@ -3871,7 +4495,6 @@ function kn(ctx) {
     metricValidate: (knId, body) => validateMetric(ctx, knId, body),
     objectTypes: (knId, opts) => listObjectTypes(ctx, knId, opts),
     objectTypeQuery: (knId, otId, body) => queryObjectTypeInstances(ctx, knId, otId, body),
-    objectTypeProperties: (knId, otId) => getObjectTypeProperties(ctx, knId, otId),
     objectTypeGet: (knId, id) => getSchemaItem(ctx, knId, "object-types", id),
     objectTypeCreate: (knId, body) => createSchemaItem(ctx, knId, "object-types", body),
     objectTypeUpdate: (knId, id, body) => updateSchemaItem(ctx, knId, "object-types", id, body),
@@ -3899,10 +4522,6 @@ function kn(ctx) {
     actionScheduleUpdate: (knId, scheduleId, body) => updateActionSchedule(ctx, knId, scheduleId, body),
     actionScheduleSetStatus: (knId, scheduleId, body) => setActionScheduleStatus(ctx, knId, scheduleId, body),
     actionScheduleDelete: (knId, ids) => deleteActionSchedules(ctx, knId, ids),
-    jobs: (knId) => listJobs(ctx, knId),
-    job: (knId, jobId) => getJob(ctx, knId, jobId),
-    jobTasks: (knId, jobId) => getJobTasks(ctx, knId, jobId),
-    jobDelete: (knId, ids) => deleteJobs(ctx, knId, ids),
     relationTypePaths: (knId, body) => relationTypePaths(ctx, knId, body),
     bknResources: () => listBknResources(ctx),
     createFromCatalog: (opts) => createFromCatalog(ctx, opts),
@@ -4155,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 });
 }
@@ -4205,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 }
   });
 }
@@ -4248,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 });
@@ -4264,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),
@@ -4287,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 };
@@ -4366,8 +5212,14 @@ function listToolboxes(ctx, opts = {}) {
     query: { keyword: opts.keyword || void 0, limit: opts.limit, offset: opts.offset ?? 0 }
   });
 }
-function listTools2(ctx, boxId) {
-  return request(ctx, `${PATH}/${encodeURIComponent(boxId)}/tools/list`);
+function listTools2(ctx, boxId, opts = {}) {
+  return request(ctx, `${PATH}/${encodeURIComponent(boxId)}/tools/list`, {
+    query: {
+      page: opts.page,
+      page_size: Number.isFinite(opts.pageSize) && opts.pageSize > 0 ? opts.pageSize : void 0,
+      all: opts.all ? "true" : void 0
+    }
+  });
 }
 function createToolbox(ctx, opts) {
   return request(ctx, PATH, {
@@ -4426,7 +5278,7 @@ function setToolStatuses(ctx, boxId, updates) {
 function toolboxes(ctx) {
   return {
     list: (opts) => listToolboxes(ctx, opts),
-    tools: (boxId) => listTools2(ctx, boxId),
+    tools: (boxId, opts) => listTools2(ctx, boxId, opts),
     create: (opts) => createToolbox(ctx, opts),
     delete: (boxId) => deleteToolbox(ctx, boxId),
     publish: (boxId) => setToolboxStatus(ctx, boxId, "published"),
@@ -4452,8 +5304,385 @@ function toolboxes(ctx) {
   };
 }
 
+// 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"
+]);
+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)}`)
+  };
+}
+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`);
+      }
+      pending.push(nested);
+    }
+  }
+}
+
+// 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;
+  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;
+      }
+      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.pendingConversations.set(externalConversationKey, request2);
+    try {
+      return await request2;
+    } finally {
+      if (this.pendingConversations.get(externalConversationKey) === request2) {
+        this.pendingConversations.delete(externalConversationKey);
+      }
+    }
+  }
+  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
+      }
+    );
+    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 };
+      }
+      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;
+      }
+      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;
+      }
+      assertSameReceipt(current.receipt, result.receipt);
+      recordReceipt(result.receipt);
+      if (isCompletedReceipt(result.receipt)) {
+        return { ...result, recovered: false };
+      }
+      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`
+        );
+      }
+    }
+  }
+};
+function assertSafeStrategy(strategy) {
+  if (!strategy || typeof strategy !== "object") {
+    throw new InputError("A conversation strategy is required");
+  }
+  for (const field of FORBIDDEN_INPUT_FIELDS2) {
+    if (field in strategy) throw new InputError(`Lifecycle input field "${field}" is not allowed`);
+  }
+}
+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 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);
   if (Number.isNaN(ms)) return void 0;
@@ -4495,6 +5724,9 @@ async function getRawSpansByConversation(ctx, conversationId, opts = {}) {
 function traceSearch(ctx, body) {
   return request(ctx, SEARCH, { method: "POST", body });
 }
+function getTraceGraph(ctx, traceId) {
+  return request(ctx, `${TRACES}/${encodeURIComponent(traceId)}/trace-graph`);
+}
 async function getSpansByConversation(ctx, conversationId, opts = {}) {
   const agg = await request(ctx, SEARCH, {
     method: "POST",
@@ -4580,10 +5812,10 @@ async function judgeJson(prompt, opts = {}) {
     child.stdout.on("data", (d) => {
       out += d;
     });
-    child.on("error", (err) => {
+    child.on("error", (err2) => {
       clearTimeout(killer);
       reject(
-        err.code === "ENOENT" ? new ClaudeJudgeError("`claude` not found on PATH", "not_available") : err
+        err2.code === "ENOENT" ? new ClaudeJudgeError("`claude` not found on PATH", "not_available") : err2
       );
     });
     child.on("close", (code) => {
@@ -4593,8 +5825,8 @@ async function judgeJson(prompt, opts = {}) {
       if (code !== 0) return reject(new ClaudeJudgeError(`claude exited ${code}`, "exit"));
       resolve7(out);
     });
-    child.stdin.on("error", (err) => {
-      if (err.code !== "EPIPE") reject(err);
+    child.stdin.on("error", (err2) => {
+      if (err2.code !== "EPIPE") reject(err2);
     });
     child.stdin.end(prompt);
   });
@@ -5144,6 +6376,747 @@ async function runEvalSet(agentId, cases, deps) {
   };
 }
 
+// src/bkn-trace/fixture-validate.ts
+import { readFileSync as readFileSync4, readdirSync as readdirSync5, statSync as statSync4 } from "fs";
+import { join as join4 } from "path";
+var CONTRACT_VERSIONS = /* @__PURE__ */ new Set(["1.0.0", "2.0.0", "2.1.0"]);
+var BUSINESS_CONTRACT_VERSION = "2.1.0";
+var TRACEPARENT_RE2 = /^00-([0-9a-f]{32})-([0-9a-f]{16})-[0-9a-f]{2}$/;
+var REQUEST_ID_RE2 = /^req_[0-9A-Za-z_.-]+$/;
+var RFC3339_NANO_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?Z$/;
+var ALLOWED_BAGGAGE2 = /* @__PURE__ */ new Set(["bkn.account.type", "bkn.runtime.env"]);
+var REQUIRED_LOG_FIELDS = [
+  "trace_id",
+  "span_id",
+  "bkn.request.id",
+  "bkn.module.name",
+  "bkn.operation.name",
+  "bkn.status",
+  "bkn.timestamp",
+  "bkn.trace.schema.version"
+];
+var REQUIRED_SPAN_FIELDS = [
+  "span_id",
+  "name",
+  "bkn.module.name",
+  "bkn.operation.name",
+  "bkn.status",
+  "bkn.timestamp"
+];
+var REQUIRED_EVENT_FIELDS = [
+  "trace_id",
+  "span_id",
+  "bkn.request.id",
+  "bkn.operation.name",
+  "event_id",
+  "event_type",
+  "bkn.trace.schema.version",
+  "observed_at",
+  "emitted_at",
+  "producer_module",
+  "payload"
+];
+var SENSITIVE_PATTERNS = [
+  /authorization/i,
+  /bearer\s+[A-Za-z0-9._-]+/i,
+  /access[_-]?token/i,
+  /api[_-]?key/i,
+  /cookie/i,
+  /\bselect\s+.+\s+from\b/is,
+  /prompt\s*[:=]/i,
+  /https?:\/\/[^\s"']+/i,
+  /[\w.+-]+@[\w.-]+\.[A-Za-z]{2,}/
+];
+var BUSINESS_EVENT_TYPES = /* @__PURE__ */ new Set([
+  "agent.interaction.started",
+  "retrieval.completed",
+  "knowledge.read.observed",
+  "data.query.observed",
+  "model.call.observed",
+  "tool.called",
+  "tool.result.observed",
+  "claim.created",
+  "evidence.refs.created",
+  "business.refs.resolved",
+  "action.recommended",
+  "action.approval_requested",
+  "action.approved",
+  "action.rejected",
+  "action.executed",
+  "action.result_recorded"
+]);
+var CLAIM_EVENT_TYPES = /* @__PURE__ */ new Set([
+  "claim.created",
+  "evidence.refs.created",
+  "business.refs.resolved",
+  "action.recommended",
+  "action.approval_requested",
+  "action.approved",
+  "action.rejected",
+  "action.executed",
+  "action.result_recorded"
+]);
+var ACTION_TRANSITIONS = {
+  recommended: /* @__PURE__ */ new Set(["approval_requested"]),
+  approval_requested: /* @__PURE__ */ new Set(["approved", "rejected"]),
+  approved: /* @__PURE__ */ new Set(["executed"]),
+  executed: /* @__PURE__ */ new Set(["result_recorded"]),
+  rejected: /* @__PURE__ */ new Set(),
+  result_recorded: /* @__PURE__ */ new Set()
+};
+var ACTION_STATE_BY_EVENT = {
+  "action.recommended": "recommended",
+  "action.approval_requested": "approval_requested",
+  "action.approved": "approved",
+  "action.rejected": "rejected",
+  "action.executed": "executed",
+  "action.result_recorded": "result_recorded"
+};
+var EVENT_PAYLOAD_FIELDS = {
+  "agent.interaction.started": /* @__PURE__ */ new Set(["intent_hash", "mode", "agent_id", "app_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"
+  ]),
+  "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"
+  ]),
+  "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"
+  ]),
+  "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",
+    "invocation_ref",
+    "tool_ref",
+    "status",
+    "error_category",
+    "error_hash"
+  ]),
+  "action.result_recorded": /* @__PURE__ */ new Set([
+    "action_instance_id",
+    "result_hash",
+    "artifact_ref",
+    "task_ref",
+    "status"
+  ])
+};
+var REFERENCE_FIELDS = /* @__PURE__ */ new Set([
+  "ref_id",
+  "ref_type",
+  "source_system",
+  "validity",
+  "version_status",
+  "visibility",
+  "summary_hash"
+]);
+var FORBIDDEN_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"
+]);
+function err(code, path, message) {
+  return { code, path, message };
+}
+function asRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function jsonFiles(path) {
+  const stat = statSync4(path);
+  if (stat.isFile()) return [path];
+  return readdirSync5(path).filter((name) => name.endsWith(".json")).sort().map((name) => join4(path, name));
+}
+function validTraceparent(value) {
+  if (typeof value !== "string") return false;
+  const match = TRACEPARENT_RE2.exec(value);
+  if (!match) return false;
+  const [, traceId, spanId] = match;
+  return traceId !== "0".repeat(32) && spanId !== "0".repeat(16);
+}
+function checkRequired(item, fields, basePath, errors) {
+  for (const field of fields) {
+    if (item[field] === void 0 || item[field] === "") {
+      errors.push(
+        err(
+          "BKN_TRACE_REQUIRED_FIELD_MISSING",
+          `${basePath}.${field}`,
+          `missing required field ${field}`
+        )
+      );
+    }
+  }
+}
+function checkTimestamp(value, path, errors) {
+  if (typeof value !== "string" || !RFC3339_NANO_RE.test(value)) {
+    errors.push(err("BKN_TRACE_INVALID_TIMESTAMP", path, "timestamp must be UTC RFC3339Nano"));
+  }
+}
+function checkSensitive(value, path, errors) {
+  if (Array.isArray(value)) {
+    value.forEach((child, index) => checkSensitive(child, `${path}[${index}]`, errors));
+    return;
+  }
+  if (value && typeof value === "object") {
+    for (const [key, child] of Object.entries(value)) {
+      if (FORBIDDEN_RAW_KEYS.has(key.toLowerCase())) {
+        errors.push(
+          err(
+            "BKN_TRACE_SENSITIVE_VALUE_LEAKED",
+            `${path}.${key}`,
+            "raw sensitive field is forbidden"
+          )
+        );
+      }
+      if (key.endsWith("_hash") && child !== "" && (typeof child !== "string" || !/^sha256:[0-9a-f]{64}$/.test(child))) {
+        errors.push(
+          err("BKN_TRACE_REQUIRED_FIELD_MISSING", `${path}.${key}`, `${key} must be a sha256 hash`)
+        );
+      }
+      checkSensitive(child, `${path}.${key}`, errors);
+    }
+    return;
+  }
+  if (typeof value !== "string") return;
+  if (SENSITIVE_PATTERNS.some((pattern) => pattern.test(value))) {
+    errors.push(
+      err(
+        "BKN_TRACE_SENSITIVE_VALUE_LEAKED",
+        path,
+        "sensitive value must be redacted, hashed, or referenced"
+      )
+    );
+  }
+}
+function validateFixture(data) {
+  const root = asRecord(data);
+  const errors = [];
+  const fixtureId = typeof root.fixture_id === "string" ? root.fixture_id : "<unknown>";
+  const contractVersion = typeof root["bkn.trace.schema.version"] === "string" ? root["bkn.trace.schema.version"] : null;
+  if (!contractVersion) {
+    errors.push(
+      err(
+        "BKN_TRACE_SCHEMA_VERSION_MISSING",
+        "$.bkn.trace.schema.version",
+        "missing contract version"
+      )
+    );
+  } else if (!CONTRACT_VERSIONS.has(contractVersion)) {
+    errors.push(
+      err(
+        "BKN_TRACE_SCHEMA_VERSION_UNSUPPORTED",
+        "$.bkn.trace.schema.version",
+        `unsupported contract version ${contractVersion}`
+      )
+    );
+  }
+  const trace2 = asRecord(root.trace);
+  const traceId = trace2.trace_id;
+  const requestId = trace2["bkn.request.id"];
+  if (typeof traceId !== "string" || !/^[0-9a-f]{32}$/.test(traceId)) {
+    errors.push(
+      err("BKN_TRACE_REQUIRED_FIELD_MISSING", "$.trace.trace_id", "missing valid trace id")
+    );
+  }
+  if (typeof requestId !== "string" || !REQUEST_ID_RE2.test(requestId)) {
+    errors.push(
+      err(
+        "BKN_TRACE_REQUIRED_FIELD_MISSING",
+        "$.trace.bkn.request.id",
+        "missing valid bkn.request.id"
+      )
+    );
+  }
+  if (!validTraceparent(trace2.traceparent)) {
+    errors.push(err("BKN_TRACE_INVALID_TRACEPARENT", "$.trace.traceparent", "invalid traceparent"));
+  }
+  const spans = Array.isArray(root.spans) ? root.spans : [];
+  const spanIds = /* @__PURE__ */ new Set();
+  spans.forEach((item, index) => {
+    const span = asRecord(item);
+    checkRequired(span, REQUIRED_SPAN_FIELDS, `$.spans[${index}]`, errors);
+    checkTimestamp(span["bkn.timestamp"], `$.spans[${index}].bkn.timestamp`, errors);
+    if (typeof span.span_id === "string") spanIds.add(span.span_id);
+    const parent = span.parent_span_id;
+    if (parent !== null && parent !== void 0 && !spanIds.has(String(parent))) {
+      errors.push(
+        err(
+          "BKN_TRACE_ORPHAN_SPAN",
+          `$.spans[${index}].parent_span_id`,
+          "parent span must appear before child span or be represented as a link"
+        )
+      );
+    }
+  });
+  if (spans.length === 0) {
+    errors.push(err("BKN_TRACE_REQUIRED_FIELD_MISSING", "$.spans", "at least one span required"));
+  }
+  const logs = Array.isArray(root.logs) ? root.logs : [];
+  logs.forEach((item, index) => {
+    const log = asRecord(item);
+    checkRequired(log, REQUIRED_LOG_FIELDS, `$.logs[${index}]`, errors);
+    checkTimestamp(log["bkn.timestamp"], `$.logs[${index}].bkn.timestamp`, errors);
+    if (log.trace_id !== traceId || log["bkn.request.id"] !== requestId) {
+      errors.push(
+        err("BKN_TRACE_JOIN_FAILED", `$.logs[${index}]`, "log cannot join trace/request")
+      );
+    }
+    if (!spanIds.has(String(log.span_id))) {
+      errors.push(
+        err("BKN_TRACE_JOIN_FAILED", `$.logs[${index}].span_id`, "log span_id not found")
+      );
+    }
+  });
+  const events = Array.isArray(root.events) ? root.events : [];
+  const eventIds = /* @__PURE__ */ new Set();
+  const knownEventIds = /* @__PURE__ */ new Set();
+  const knownOperationIds = /* @__PURE__ */ new Set();
+  const knownClaimIds = /* @__PURE__ */ new Set();
+  const actionStates = /* @__PURE__ */ new Map();
+  events.forEach((item, index) => {
+    const event = asRecord(item);
+    const eventPath = `$.events[${index}]`;
+    checkRequired(event, REQUIRED_EVENT_FIELDS, `$.events[${index}]`, errors);
+    checkTimestamp(event.observed_at, `$.events[${index}].observed_at`, errors);
+    checkTimestamp(event.emitted_at, `$.events[${index}].emitted_at`, errors);
+    if (event.trace_id !== traceId || event["bkn.request.id"] !== requestId) {
+      errors.push(
+        err("BKN_TRACE_JOIN_FAILED", `$.events[${index}]`, "event cannot join trace/request")
+      );
+    }
+    if (!spanIds.has(String(event.span_id))) {
+      errors.push(
+        err("BKN_TRACE_JOIN_FAILED", `$.events[${index}].span_id`, "event span_id not found")
+      );
+    }
+    if (typeof event.event_id === "string") {
+      if (eventIds.has(event.event_id)) {
+        errors.push(
+          err("BKN_TRACE_EVENT_ID_CONFLICT", `${eventPath}.event_id`, "duplicate event_id")
+        );
+      }
+      eventIds.add(event.event_id);
+    }
+    if (contractVersion !== BUSINESS_CONTRACT_VERSION) return;
+    if (event["bkn.trace.schema.version"] !== contractVersion) {
+      errors.push(
+        err(
+          "BKN_TRACE_SCHEMA_VERSION_UNSUPPORTED",
+          `${eventPath}.bkn.trace.schema.version`,
+          "event contract version must match the fixture envelope"
+        )
+      );
+    }
+    validateBusinessEvent(
+      event,
+      eventPath,
+      knownEventIds,
+      knownOperationIds,
+      knownClaimIds,
+      actionStates,
+      errors
+    );
+    if (typeof event.event_id === "string") knownEventIds.add(event.event_id);
+    if (typeof event.operation_id === "string") knownOperationIds.add(event.operation_id);
+    if (event.event_type === "claim.created" && typeof event.claim_id === "string") {
+      knownClaimIds.add(event.claim_id);
+    }
+  });
+  if (contractVersion !== "1.0.0" && events.length === 0) {
+    errors.push(err("BKN_TRACE_REQUIRED_FIELD_MISSING", "$.events", "at least one event required"));
+  }
+  const baggage = asRecord(root.baggage);
+  for (const key of Object.keys(baggage)) {
+    if (!ALLOWED_BAGGAGE2.has(key)) {
+      errors.push(
+        err(
+          "BKN_TRACE_BAGGAGE_FORBIDDEN_FIELD",
+          `$.baggage.${key}`,
+          `baggage field ${key} is forbidden`
+        )
+      );
+    }
+  }
+  checkSensitive(root, "$", errors);
+  const result = errors.length > 0 ? "fail" : "pass";
+  const expectedResult = root.expected_result === "pass" || root.expected_result === "fail" ? root.expected_result : null;
+  return {
+    fixtureId,
+    result,
+    contractVersion,
+    errors,
+    warnings: [],
+    expectedResult,
+    expectationMatched: expectedResult === null ? result === "pass" : expectedResult === result
+  };
+}
+function validateBusinessEvent(event, path, knownEventIds, knownOperationIds, knownClaimIds, actionStates, errors) {
+  const eventType = typeof event.event_type === "string" ? event.event_type : "";
+  if (!BUSINESS_EVENT_TYPES.has(eventType)) {
+    errors.push(
+      err(
+        "BKN_TRACE_EVENT_TYPE_UNSUPPORTED",
+        `${path}.event_type`,
+        `unsupported event ${eventType}`
+      )
+    );
+    return;
+  }
+  checkRequired(event, ["interaction_id"], path, errors);
+  if (eventType !== "agent.interaction.started" && eventType !== "claim.created") {
+    checkRequired(event, ["operation_id"], path, errors);
+  }
+  if (eventType !== "agent.interaction.started") {
+    checkRequired(event, ["causation_event_id"], path, errors);
+    if (typeof event.causation_event_id === "string" && !knownEventIds.has(event.causation_event_id)) {
+      errors.push(
+        err(
+          "BKN_TRACE_CAUSATION_INVALID",
+          `${path}.causation_event_id`,
+          "causation_event_id must reference an earlier event"
+        )
+      );
+    }
+  }
+  if (CLAIM_EVENT_TYPES.has(eventType)) {
+    checkRequired(event, ["claim_id"], path, errors);
+    if (eventType !== "claim.created" && typeof event.claim_id === "string" && !knownClaimIds.has(event.claim_id)) {
+      errors.push(
+        err(
+          "BKN_TRACE_UNKNOWN_CLAIM_ID",
+          `${path}.claim_id`,
+          "event must reference an earlier claim"
+        )
+      );
+    }
+  }
+  const payload = asRecord(event.payload);
+  checkAllowedKeys(
+    payload,
+    EVENT_PAYLOAD_FIELDS[eventType] ?? /* @__PURE__ */ new Set(),
+    `${path}.payload`,
+    errors
+  );
+  if (eventType === "agent.interaction.started") {
+    checkRequired(payload, ["intent_hash", "mode"], `${path}.payload`, errors);
+    checkOneOf(payload, ["agent_id", "app_ref"], `${path}.payload`, errors);
+  }
+  if (eventType === "retrieval.completed") {
+    checkRequired(
+      payload,
+      ["query_hash", "candidate_count", "truncated"],
+      `${path}.payload`,
+      errors
+    );
+  }
+  if (eventType === "knowledge.read.observed") {
+    checkRequired(payload, ["kn_id", "read_kind", "version_status"], `${path}.payload`, errors);
+  }
+  if (eventType === "data.query.observed") {
+    checkRequired(payload, ["query_hash", "query_type", "row_count"], `${path}.payload`, errors);
+  }
+  if (eventType === "model.call.observed") {
+    checkRequired(
+      payload,
+      [
+        "model_name",
+        "model_provider",
+        "status",
+        "input_token_count",
+        "output_token_count",
+        "prompt_hash",
+        "output_hash"
+      ],
+      `${path}.payload`,
+      errors
+    );
+    if (payload.status === "error") {
+      checkRequired(payload, ["error_category", "error_hash"], `${path}.payload`, errors);
+    }
+  }
+  if (eventType === "claim.created") {
+    checkRequired(
+      payload,
+      [
+        "claim_id",
+        "claim_type",
+        "claim_hash",
+        "source_event_ids",
+        "operation_ids",
+        "visibility",
+        "version_status"
+      ],
+      `${path}.payload`,
+      errors
+    );
+    checkNonEmptyArray(payload, "source_event_ids", `${path}.payload`, errors);
+    checkNonEmptyArray(payload, "operation_ids", `${path}.payload`, errors);
+    checkKnownArray(payload, "source_event_ids", knownEventIds, `${path}.payload`, errors);
+    checkKnownArray(payload, "operation_ids", knownOperationIds, `${path}.payload`, errors);
+  }
+  if (eventType === "evidence.refs.created") {
+    checkReferenceList(payload, "evidence_refs", `${path}.payload`, errors);
+  }
+  if (eventType === "business.refs.resolved") {
+    checkRequired(payload, ["resolver_status"], `${path}.payload`, errors);
+    checkReferenceList(
+      payload,
+      "business_refs",
+      `${path}.payload`,
+      errors,
+      payload.resolver_status === "unresolved"
+    );
+  }
+  const actionState = ACTION_STATE_BY_EVENT[eventType];
+  if (!actionState) return;
+  checkRequired(payload, ["action_instance_id", "status"], `${path}.payload`, errors);
+  const fixedStatus = {
+    "action.recommended": "recommended",
+    "action.approval_requested": "approval_requested",
+    "action.approved": "approved",
+    "action.rejected": "rejected"
+  };
+  if (fixedStatus[eventType] && payload.status !== fixedStatus[eventType]) {
+    errors.push(
+      err(
+        "BKN_TRACE_ACTION_TRANSITION_INVALID",
+        `${path}.payload.status`,
+        `${eventType} requires status=${fixedStatus[eventType]}`
+      )
+    );
+  }
+  if (eventType === "action.recommended") {
+    checkRequired(
+      payload,
+      ["action_type", "target_refs", "reason_hash"],
+      `${path}.payload`,
+      errors
+    );
+    checkNonEmptyArray(payload, "target_refs", `${path}.payload`, errors);
+    checkQualifiedStringRefs(payload, "target_refs", `${path}.payload`, errors);
+  }
+  if (eventType === "action.approval_requested") {
+    checkRequired(payload, ["policy_ref"], `${path}.payload`, errors);
+  }
+  if (eventType === "action.approved" || eventType === "action.rejected") {
+    checkRequired(payload, ["actor_ref", "policy_decision_ref"], `${path}.payload`, errors);
+  }
+  if (eventType === "action.executed") {
+    checkOneOf(payload, ["invocation_ref", "tool_ref"], `${path}.payload`, errors);
+    if (payload.status === "error") {
+      checkRequired(payload, ["error_category", "error_hash"], `${path}.payload`, errors);
+    }
+  }
+  if (eventType === "action.result_recorded") {
+    checkRequired(payload, ["result_hash"], `${path}.payload`, errors);
+    checkOneOf(payload, ["artifact_ref", "task_ref"], `${path}.payload`, errors);
+  }
+  const actionID = typeof payload.action_instance_id === "string" ? payload.action_instance_id : "";
+  if (!actionID) return;
+  const claimID = typeof event.claim_id === "string" ? event.claim_id : "";
+  const operationID = typeof event.operation_id === "string" ? event.operation_id : "";
+  const previous = actionStates.get(actionID);
+  if (!previous && actionState !== "recommended" || previous && (!ACTION_TRANSITIONS[previous.state]?.has(actionState) || event.causation_event_id !== previous.lastEventID || claimID !== previous.claimID || operationID !== previous.operationID)) {
+    errors.push(
+      err(
+        "BKN_TRACE_ACTION_TRANSITION_INVALID",
+        `${path}.event_type`,
+        `invalid action transition ${previous?.state ?? "<none>"} -> ${actionState}`
+      )
+    );
+    return;
+  }
+  actionStates.set(actionID, {
+    state: actionState,
+    claimID,
+    operationID,
+    lastEventID: String(event.event_id ?? "")
+  });
+}
+function checkOneOf(payload, fields, path, errors) {
+  if (fields.some((field) => typeof payload[field] === "string" && payload[field] !== "")) return;
+  errors.push(
+    err(
+      "BKN_TRACE_REQUIRED_FIELD_MISSING",
+      `${path}.${fields[0]}`,
+      `one of ${fields.join(" or ")} is required`
+    )
+  );
+}
+function checkNonEmptyArray(payload, field, path, errors) {
+  if (Array.isArray(payload[field]) && payload[field].length > 0) return;
+  errors.push(
+    err(
+      "BKN_TRACE_REQUIRED_FIELD_MISSING",
+      `${path}.${field}`,
+      `${field} must be a non-empty array`
+    )
+  );
+}
+function checkReferenceList(payload, field, path, errors, allowEmpty = false) {
+  if (!allowEmpty) checkNonEmptyArray(payload, field, path, errors);
+  const refs = Array.isArray(payload[field]) ? payload[field] : [];
+  refs.forEach((value, index) => {
+    const ref = asRecord(value);
+    checkRequired(
+      ref,
+      ["ref_id", "ref_type", "source_system", "validity", "version_status", "visibility"],
+      `${path}.${field}[${index}]`,
+      errors
+    );
+    checkAllowedKeys(ref, REFERENCE_FIELDS, `${path}.${field}[${index}]`, errors);
+    if (typeof ref.ref_id === "string" && !isQualifiedReference(ref.ref_id)) {
+      errors.push(
+        err(
+          "BKN_TRACE_REFERENCE_ID_INVALID",
+          `${path}.${field}[${index}].ref_id`,
+          "business reference id must include its knowledge-network or resource scope"
+        )
+      );
+    }
+  });
+}
+function checkQualifiedStringRefs(payload, field, path, errors) {
+  const refs = Array.isArray(payload[field]) ? payload[field] : [];
+  refs.forEach((value, index) => {
+    if (typeof value !== "string" || isQualifiedReference(value)) return;
+    errors.push(
+      err(
+        "BKN_TRACE_REFERENCE_ID_INVALID",
+        `${path}.${field}[${index}]`,
+        "business reference id must include its knowledge-network or resource scope"
+      )
+    );
+  });
+}
+function isQualifiedReference(value) {
+  const parts = value.trim().split(":");
+  if (parts.some((part) => part.length === 0)) return false;
+  if (["kn", "resource"].includes(parts[0] ?? "")) return parts.length === 2;
+  if (["object", "relation", "action_type", "metric", "field"].includes(parts[0] ?? "")) {
+    return parts.length === 3;
+  }
+  if (parts[0] === "property") return parts.length === 4;
+  return true;
+}
+function checkKnownArray(payload, field, known, path, errors) {
+  if (!Array.isArray(payload[field])) return;
+  for (const value of payload[field]) {
+    if (typeof value === "string" && known.has(value)) continue;
+    errors.push(
+      err(
+        "BKN_TRACE_CAUSATION_INVALID",
+        `${path}.${field}`,
+        `${field} must reference earlier events or operations`
+      )
+    );
+  }
+}
+function checkAllowedKeys(value, allowed, path, errors) {
+  for (const key of Object.keys(value)) {
+    if (allowed.has(key)) continue;
+    errors.push(
+      err(
+        "BKN_TRACE_EVENT_PAYLOAD_FIELD_UNSUPPORTED",
+        `${path}.${key}`,
+        `payload field ${key} is not registered for this event`
+      )
+    );
+  }
+}
+function validateFixturePath(path) {
+  const results = jsonFiles(path).map((file) => {
+    try {
+      return validateFixture(JSON.parse(readFileSync4(file, "utf8")));
+    } catch (e) {
+      return {
+        fixtureId: file,
+        result: "fail",
+        contractVersion: null,
+        errors: [
+          err(
+            "BKN_TRACE_FIXTURE_PARSE_FAILED",
+            "$",
+            `failed to parse JSON: ${e instanceof Error ? e.message : String(e)}`
+          )
+        ],
+        warnings: [],
+        expectedResult: null,
+        expectationMatched: false
+      };
+    }
+  });
+  return { ok: results.every((r) => r.expectationMatched), results };
+}
+
 // src/resources/trace.ts
 async function semanticJudge(question, answer, reference) {
   const prompt = [
@@ -5160,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}`);
@@ -5188,8 +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),
+    /** Normalized trace tree/status graph by trace id. */
+    graph: (traceId) => getTraceGraph(ctx, traceId),
     /** All span source docs for a conversation. */
     spans: (conversationId, opts) => getSpansByConversation(ctx, conversationId, opts),
     diagnose: diagnoseOne,
@@ -5227,6 +7208,8 @@ function trace(ctx) {
     },
     /** Build eval cases from a loosely-shaped queries object/array. */
     evalSetBuild: (raw) => buildCasesFromQueries(raw),
+    /** Validate BKN Trace phase-one fixture files or directories. */
+    validateFixture: (path) => validateFixturePath(path),
     /**
      * Run an eval set against an agent: each case's query is sent to the agent,
      * the resulting trace is fetched, and assertions are checked. `llm` enables
@@ -5259,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) => listCatalogResources(ctx, id, category),
-    catalogHealth: (ids) => catalogHealthStatus(ctx, ids),
+    catalogResources: (id, category, limit, offset) => listCatalogResources(ctx, id, category, limit, offset),
+    catalogHealth: (id) => catalogHealthStatus(ctx, id),
     connectorTypes: () => listConnectorTypes(ctx),
     connectorType: (type) => getConnectorType(ctx, type),
     /** Run SQL / OpenSearch DSL directly against a data source. */
@@ -5300,7 +7286,7 @@ function sleep(ms) {
 }
 
 // src/api/call.ts
-import { readFileSync as readFileSync4 } from "fs";
+import { readFileSync as readFileSync5 } from "fs";
 function parseHeader(raw) {
   const idx = raw.indexOf(":");
   if (idx <= 0) return null;
@@ -5329,7 +7315,7 @@ async function rawCall(ctx, path, opts = {}) {
     const fd = new FormData();
     for (const field of opts.form) {
       const [key, value, isFile] = parseFormField(field);
-      if (isFile) fd.append(key, new Blob([readFileSync4(value)]), value.split("/").pop());
+      if (isFile) fd.append(key, new Blob([readFileSync5(value)]), value.split("/").pop());
       else fd.append(key, value);
     }
     body = fd;
@@ -5414,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),
@@ -5452,7 +7438,7 @@ function hostOf(baseUrl) {
     return baseUrl;
   }
 }
-function normalize(baseUrl) {
+function normalize2(baseUrl) {
   return baseUrl.replace(/\/+$/, "");
 }
 function usernameOf(token) {
@@ -5461,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,
@@ -5564,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.`);
   }
@@ -5575,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) {
@@ -5589,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() {
@@ -5607,6 +7593,7 @@ function exportCreds() {
 
 export {
   HttpError,
+  ToolError,
   InputError,
   toExitCode,
   formatError,
@@ -5615,6 +7602,7 @@ export {
   deviceLogin,
   credentialDeviceLogin,
   request,
+  lifecycleHint,
   rawCall,
   DEFAULT_BUSINESS_DOMAIN,
   DEFAULT_LIST_LIMIT,
@@ -5628,7 +7616,8 @@ export {
   getUserSafe,
   changePasswordSafe,
   admin,
-  agents,
+  agents2 as agents,
+  releaseLifecycleSessions,
   context,
   dataflows,
   parsePkMap,
@@ -5636,9 +7625,15 @@ export {
   kn,
   models,
   resources,
+  classifyPath,
+  filesUnder,
+  renderTree,
   skills,
   toolboxes,
+  traceLifecycleApi,
   renderReportMarkdown,
+  validateFixturePath,
+  ManagedTrace,
   trace,
   vega,
   createClient,
@@ -5655,4 +7650,4 @@ export {
   exportCreds,
   auth_exports
 };
-//# sourceMappingURL=chunk-NC6DZ2AU.js.map
+//# sourceMappingURL=chunk-PC2F54XD.js.map