@qloo/qloo-harness 0.1.18

package/dist/qloo-tools.js

@@ -0,0 +1,2195 @@
+import { createRequire as __qlooCreateRequire } from "node:module";
+const require = __qlooCreateRequire(import.meta.url);
+
+// packages/qloo-client-ts/dist/config.js
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, parse, resolve } from "node:path";
+var QLOO_PRODUCTION_BASE_URL = "https://api.qloo.com";
+function nonEmptyString(value) {
+  if (typeof value !== "string")
+    return void 0;
+  const trimmed = value.trim();
+  return trimmed || void 0;
+}
+function selectFileConfig(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value))
+    return {};
+  const record = value;
+  const apiKey = nonEmptyString(record.api_key);
+  const baseUrl = nonEmptyString(record.base_url);
+  const trustedBaseUrl = nonEmptyString(record.trusted_base_url);
+  const tasteResolverUrl = nonEmptyString(record.taste_resolver_url);
+  return {
+    ...apiKey ? { api_key: apiKey } : {},
+    ...baseUrl ? { base_url: baseUrl } : {},
+    ...trustedBaseUrl ? { trusted_base_url: trustedBaseUrl } : {},
+    ...tasteResolverUrl ? { taste_resolver_url: tasteResolverUrl } : {}
+  };
+}
+function comparableBaseUrl(value) {
+  try {
+    const url = new URL(value);
+    if (url.username || url.password || url.search || url.hash)
+      return void 0;
+    url.pathname = url.pathname.replace(/\/+$/u, "") || "/";
+    return url.toString();
+  } catch {
+    return void 0;
+  }
+}
+function areEquivalentQlooBaseUrls(left, right) {
+  const normalizedLeft = comparableBaseUrl(left);
+  return normalizedLeft !== void 0 && normalizedLeft === comparableBaseUrl(right);
+}
+function isOfficialQlooBaseUrl(value) {
+  return areEquivalentQlooBaseUrls(value, QLOO_PRODUCTION_BASE_URL);
+}
+function parseQlooConfig(content) {
+  const trimmed = content.trim();
+  if (!trimmed)
+    return {};
+  if (trimmed.startsWith("{"))
+    return selectFileConfig(JSON.parse(trimmed));
+  const values = {};
+  for (const line of content.split(/\r?\n/u)) {
+    const candidate = line.trim();
+    if (!candidate || candidate.startsWith("#"))
+      continue;
+    const separator = candidate.indexOf("=");
+    if (separator < 0)
+      continue;
+    const key = candidate.slice(0, separator).trim();
+    let value = candidate.slice(separator + 1).trim();
+    if (value.length >= 2 && (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+    values[key] = value;
+  }
+  return selectFileConfig(values);
+}
+function loadQlooConfig(configPath, readFile) {
+  try {
+    const content = readFile ? readFile(configPath) : readFileSync(configPath, "utf8");
+    return parseQlooConfig(content);
+  } catch {
+    return {};
+  }
+}
+function resolveQlooConfigPath(options = {}) {
+  const env = options.env ?? process.env;
+  const homeDirectory = resolve(options.homeDirectory ?? homedir());
+  const configuredRoot = nonEmptyString(env.QLOO_HOME);
+  if (!configuredRoot)
+    return join(homeDirectory, ".qloo", "config");
+  const root = configuredRoot === "~" ? homeDirectory : configuredRoot.startsWith("~/") || configuredRoot.startsWith("~\\") ? join(homeDirectory, configuredRoot.slice(2)) : isAbsolute(configuredRoot) ? resolve(configuredRoot) : resolve(configuredRoot);
+  if (root === homeDirectory || root === parse(root).root) {
+    throw new Error("QLOO_HOME must name a dedicated subdirectory, not a home or filesystem root.");
+  }
+  return join(root, "config");
+}
+function resolveQlooClientConfiguration(options = {}) {
+  const env = options.env ?? process.env;
+  const configPath = options.configPath ?? resolveQlooConfigPath({ env });
+  const fileConfig = loadQlooConfig(configPath, options.readFile);
+  const environmentApiKey = nonEmptyString(env.QLOO_API_KEY);
+  const environmentBaseUrl = nonEmptyString(env.QLOO_BASE_URL);
+  const environmentTrustedBaseUrl = nonEmptyString(env.QLOO_TRUSTED_BASE_URL);
+  const apiKey = environmentApiKey ?? fileConfig.api_key;
+  const baseUrl = environmentBaseUrl ?? fileConfig.base_url;
+  const effectiveBaseUrl = baseUrl ?? QLOO_PRODUCTION_BASE_URL;
+  const baseUrlTrustSource = isOfficialQlooBaseUrl(effectiveBaseUrl) ? "official" : environmentTrustedBaseUrl && areEquivalentQlooBaseUrls(effectiveBaseUrl, environmentTrustedBaseUrl) ? "environment" : fileConfig.trusted_base_url && areEquivalentQlooBaseUrls(effectiveBaseUrl, fileConfig.trusted_base_url) ? "config" : "missing";
+  return {
+    ...apiKey ? { apiKey } : {},
+    apiKeySource: environmentApiKey ? "environment" : fileConfig.api_key ? "config" : "missing",
+    ...baseUrl ? { baseUrl } : {},
+    baseUrlSource: environmentBaseUrl ? "environment" : fileConfig.base_url ? "config" : "default",
+    baseUrlTrusted: baseUrlTrustSource !== "missing",
+    baseUrlTrustSource,
+    fileConfig
+  };
+}
+
+// packages/qloo-client-ts/dist/errors.js
+var QlooClientError = class extends Error {
+  code;
+  retryable;
+  status;
+  requestId;
+  details;
+  constructor(code, message, options = {}) {
+    super(message, options.cause === void 0 ? void 0 : { cause: options.cause });
+    this.name = "QlooClientError";
+    this.code = code;
+    this.retryable = options.retryable ?? false;
+    if (options.status !== void 0)
+      this.status = options.status;
+    if (options.requestId !== void 0)
+      this.requestId = options.requestId;
+    if (options.details !== void 0)
+      this.details = options.details;
+  }
+  toJSON() {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      retryable: this.retryable,
+      ...this.status === void 0 ? {} : { status: this.status },
+      ...this.requestId === void 0 ? {} : { requestId: this.requestId },
+      ...this.details === void 0 ? {} : { details: this.details }
+    };
+  }
+};
+var DNS_CODES = /* @__PURE__ */ new Set([
+  "EAI_AGAIN",
+  "EAI_FAIL",
+  "ENODATA",
+  "ENOTFOUND",
+  "ENOTIMP",
+  "ENOTINITIALIZED",
+  "ESERVFAIL"
+]);
+var CONNECTION_CODES = /* @__PURE__ */ new Set([
+  "ECONNABORTED",
+  "ECONNREFUSED",
+  "ECONNRESET",
+  "EHOSTDOWN",
+  "EHOSTUNREACH",
+  "ENETDOWN",
+  "ENETUNREACH",
+  "EPIPE",
+  "ETIMEDOUT",
+  "UND_ERR_CONNECT_TIMEOUT",
+  "UND_ERR_SOCKET"
+]);
+var TLS_CODES = /* @__PURE__ */ new Set([
+  "CERT_HAS_EXPIRED",
+  "CERT_NOT_YET_VALID",
+  "DEPTH_ZERO_SELF_SIGNED_CERT",
+  "ERR_TLS_CERT_ALTNAME_INVALID",
+  "SELF_SIGNED_CERT_IN_CHAIN",
+  "UNABLE_TO_GET_ISSUER_CERT",
+  "UNABLE_TO_GET_ISSUER_CERT_LOCALLY",
+  "UNABLE_TO_VERIFY_LEAF_SIGNATURE"
+]);
+var PROXY_CODES = /* @__PURE__ */ new Set([
+  "ERR_PROXY_AUTH_UNSUPPORTED",
+  "UND_ERR_PRX"
+]);
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function safeErrorCode(value) {
+  if (!isRecord(value))
+    return void 0;
+  const code = value.code;
+  return typeof code === "string" && /^[A-Z][A-Z0-9_]{1,63}$/u.test(code) ? code : void 0;
+}
+function errorChain(value) {
+  const chain = [];
+  const seen = /* @__PURE__ */ new Set();
+  let current = value;
+  for (let depth = 0; depth < 8 && current !== void 0 && !seen.has(current); depth += 1) {
+    chain.push(current);
+    seen.add(current);
+    if (!isRecord(current))
+      break;
+    if (Array.isArray(current.errors) && current.errors.length > 0) {
+      chain.push(...current.errors.slice(0, 4));
+    }
+    current = current.cause;
+  }
+  return chain;
+}
+function classifyQlooNetworkFailure(cause) {
+  const chain = errorChain(cause);
+  const systemCode = chain.map(safeErrorCode).find((value) => value !== void 0);
+  const names = chain.map((value) => isRecord(value) && typeof value.name === "string" ? value.name : void 0).filter((value) => value !== void 0);
+  if (names.includes("AbortError") || systemCode === "ABORT_ERR") {
+    return {
+      code: "QLOO_ABORTED",
+      kind: "aborted",
+      message: "Qloo API request was cancelled.",
+      retryable: false,
+      ...systemCode ? { systemCode } : {}
+    };
+  }
+  if (systemCode && DNS_CODES.has(systemCode)) {
+    return {
+      code: "QLOO_DNS_ERROR",
+      kind: "dns",
+      message: "Could not resolve the Qloo API hostname. Check DNS and VPN configuration.",
+      retryable: true,
+      systemCode
+    };
+  }
+  if (systemCode && (TLS_CODES.has(systemCode) || systemCode.startsWith("ERR_TLS_") || systemCode.startsWith("ERR_SSL_"))) {
+    return {
+      code: "QLOO_TLS_ERROR",
+      kind: "tls",
+      message: "Could not establish a trusted TLS connection to the Qloo API.",
+      retryable: false,
+      systemCode
+    };
+  }
+  if (systemCode && PROXY_CODES.has(systemCode)) {
+    return {
+      code: "QLOO_PROXY_ERROR",
+      kind: "proxy",
+      message: "The configured network proxy could not reach the Qloo API.",
+      retryable: true,
+      systemCode
+    };
+  }
+  if (systemCode && CONNECTION_CODES.has(systemCode)) {
+    return {
+      code: "QLOO_CONNECTION_ERROR",
+      kind: "connection",
+      message: "Could not open a connection to the Qloo API. Check VPN, routing, and firewall configuration.",
+      retryable: true,
+      systemCode
+    };
+  }
+  return {
+    code: "QLOO_NETWORK_ERROR",
+    kind: "network",
+    message: "Unable to reach the Qloo API because of an unclassified network failure.",
+    retryable: true,
+    ...systemCode ? { systemCode } : {}
+  };
+}
+
+// packages/qloo-client-ts/dist/client.js
+var DEFAULT_TIMEOUT_MS = 2e4;
+var DEFAULT_MAX_ATTEMPTS = 3;
+var DEFAULT_MAX_RESPONSE_BYTES = 5 * 1024 * 1024;
+var DEFAULT_MAX_RETRY_DELAY_MS = 3e4;
+var RETRYABLE_STATUS_CODES = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
+function validatePositiveInteger(name, value) {
+  if (!Number.isSafeInteger(value) || value < 1) {
+    throw new QlooClientError("QLOO_CONFIGURATION_ERROR", `${name} must be a positive integer.`);
+  }
+}
+function normalizeBaseUrl(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch (cause) {
+    throw new QlooClientError("QLOO_CONFIGURATION_ERROR", "Qloo base URL is invalid.", {
+      cause
+    });
+  }
+  const isLoopback = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]";
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && isLoopback)) {
+    throw new QlooClientError("QLOO_CONFIGURATION_ERROR", "Qloo base URL must use HTTPS (HTTP is allowed only for a loopback test server).");
+  }
+  if (url.username || url.password || url.search || url.hash) {
+    throw new QlooClientError("QLOO_CONFIGURATION_ERROR", "Qloo base URL cannot contain credentials, query parameters, or a fragment.");
+  }
+  url.pathname = url.pathname.replace(/\/+$/, "") + "/";
+  return url;
+}
+function appendQuery(url, query) {
+  for (const [key, value] of Object.entries(query)) {
+    if (value === void 0 || value === null || value === "")
+      continue;
+    const serialized = Array.isArray(value) ? value.join(",") : String(value);
+    if (serialized !== "")
+      url.searchParams.set(key, serialized);
+  }
+}
+function requestIdFrom(response) {
+  return response.headers.get("x-qloo-request-id") ?? response.headers.get("x-request-id") ?? response.headers.get("request-id") ?? void 0;
+}
+function responseErrorMetadata(response) {
+  const requestId = requestIdFrom(response);
+  return {
+    status: response.status,
+    ...requestId ? { requestId } : {}
+  };
+}
+function retryAfterMilliseconds(response, now = Date.now()) {
+  const value = response.headers.get("retry-after");
+  if (!value)
+    return void 0;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds) && seconds >= 0)
+    return seconds * 1e3;
+  const date = Date.parse(value);
+  if (!Number.isNaN(date))
+    return Math.max(0, date - now);
+  return void 0;
+}
+function responseMessage(body, response) {
+  if (body && typeof body === "object") {
+    for (const key of ["message", "reason", "error"]) {
+      const value = Reflect.get(body, key);
+      if (typeof value === "string" && value.trim())
+        return value;
+    }
+  }
+  return `Qloo API request failed with ${response.status} ${response.statusText || "HTTP error"}.`;
+}
+function createAttemptSignal(parent, timeoutMs) {
+  const controller = new AbortController();
+  let timedOut = false;
+  const timeout = setTimeout(() => {
+    timedOut = true;
+    controller.abort(new Error("Qloo request timed out."));
+  }, timeoutMs);
+  timeout.unref?.();
+  const onParentAbort = () => controller.abort(parent?.reason);
+  if (parent?.aborted)
+    onParentAbort();
+  else
+    parent?.addEventListener("abort", onParentAbort, { once: true });
+  return {
+    signal: controller.signal,
+    didTimeout: () => timedOut,
+    dispose: () => {
+      clearTimeout(timeout);
+      parent?.removeEventListener("abort", onParentAbort);
+    }
+  };
+}
+async function defaultSleep(milliseconds, signal) {
+  if (signal?.aborted)
+    throw signal.reason;
+  await new Promise((resolve2, reject) => {
+    const cleanup = () => signal?.removeEventListener("abort", onAbort);
+    const timeout = setTimeout(() => {
+      cleanup();
+      resolve2();
+    }, milliseconds);
+    const onAbort = () => {
+      clearTimeout(timeout);
+      cleanup();
+      reject(signal?.reason);
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+async function readBoundedBody(response, maxBytes) {
+  const contentLength = response.headers.get("content-length");
+  if (contentLength !== null && Number(contentLength) > maxBytes) {
+    await response.body?.cancel();
+    throw new QlooClientError("QLOO_RESPONSE_TOO_LARGE", `Qloo API response exceeded the ${maxBytes}-byte limit.`, responseErrorMetadata(response));
+  }
+  if (!response.body)
+    return "";
+  const reader = response.body.getReader();
+  const chunks = [];
+  let total = 0;
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done)
+      break;
+    if (!value)
+      continue;
+    total += value.byteLength;
+    if (total > maxBytes) {
+      await reader.cancel();
+      throw new QlooClientError("QLOO_RESPONSE_TOO_LARGE", `Qloo API response exceeded the ${maxBytes}-byte limit.`, responseErrorMetadata(response));
+    }
+    chunks.push(value);
+  }
+  const body = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    body.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return new TextDecoder().decode(body);
+}
+function parseJsonBody(text, response) {
+  if (!text.trim())
+    return {};
+  try {
+    return JSON.parse(text);
+  } catch (cause) {
+    throw new QlooClientError("QLOO_RESPONSE_ERROR", "Qloo API returned invalid JSON.", {
+      cause,
+      retryable: response.status >= 500,
+      ...responseErrorMetadata(response)
+    });
+  }
+}
+var QlooClient = class {
+  baseUrl;
+  #apiKey;
+  #baseUrl;
+  #timeoutMs;
+  #maxAttempts;
+  #maxResponseBytes;
+  #maxRetryDelayMs;
+  #userAgent;
+  #fetch;
+  #sleep;
+  #random;
+  constructor(options) {
+    if (!options.apiKey?.trim()) {
+      throw new QlooClientError("QLOO_CONFIGURATION_ERROR", "Qloo API key is required.");
+    }
+    this.#apiKey = options.apiKey;
+    this.#baseUrl = normalizeBaseUrl(options.baseUrl ?? QLOO_PRODUCTION_BASE_URL);
+    if (!isOfficialQlooBaseUrl(this.#baseUrl.toString()) && !options.allowCustomBaseUrl) {
+      throw new QlooClientError("QLOO_CONFIGURATION_ERROR", "Custom Qloo base URL is not trusted. Approve the exact endpoint before sending credentials.");
+    }
+    this.baseUrl = this.#baseUrl.toString().replace(/\/$/, "");
+    this.#timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.#maxAttempts = options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+    this.#maxResponseBytes = options.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES;
+    this.#maxRetryDelayMs = options.maxRetryDelayMs ?? DEFAULT_MAX_RETRY_DELAY_MS;
+    this.#userAgent = options.userAgent ?? "agentic-qloo-client/0.1.0";
+    this.#fetch = options.fetch ?? globalThis.fetch;
+    this.#sleep = options.sleep ?? defaultSleep;
+    this.#random = options.random ?? Math.random;
+    validatePositiveInteger("timeoutMs", this.#timeoutMs);
+    validatePositiveInteger("maxAttempts", this.#maxAttempts);
+    validatePositiveInteger("maxResponseBytes", this.#maxResponseBytes);
+    validatePositiveInteger("maxRetryDelayMs", this.#maxRetryDelayMs);
+  }
+  async get(path, query = {}, options = {}) {
+    if (path.includes("\\") || path.startsWith("//") || /^[A-Za-z][A-Za-z\d+.-]*:/u.test(path) || /[?#\u0000-\u001f\u007f]/u.test(path)) {
+      throw new QlooClientError("QLOO_CONFIGURATION_ERROR", "Qloo request path must be a relative API path without a query or fragment.");
+    }
+    const relativePath = path.replace(/^\/+/, "");
+    const url = new URL(relativePath, this.#baseUrl);
+    if (url.origin !== this.#baseUrl.origin || !url.pathname.startsWith(this.#baseUrl.pathname)) {
+      throw new QlooClientError("QLOO_CONFIGURATION_ERROR", "Qloo request path cannot escape the trusted API base URL.");
+    }
+    appendQuery(url, query);
+    for (let attempt = 1; attempt <= this.#maxAttempts; attempt += 1) {
+      if (options.signal?.aborted)
+        throw options.signal.reason;
+      const attemptSignal = createAttemptSignal(options.signal, this.#timeoutMs);
+      let response;
+      let body;
+      try {
+        response = await this.#fetch(url, {
+          method: "GET",
+          headers: {
+            Accept: "application/json",
+            "X-Api-Key": this.#apiKey,
+            "User-Agent": this.#userAgent,
+            ...options.correlationId ? { "X-Correlation-Id": options.correlationId } : {}
+          },
+          signal: attemptSignal.signal
+        });
+        const text = await readBoundedBody(response, this.#maxResponseBytes);
+        body = parseJsonBody(text, response);
+      } catch (cause) {
+        const timedOut = attemptSignal.didTimeout();
+        attemptSignal.dispose();
+        if (options.signal?.aborted)
+          throw options.signal.reason;
+        if (cause instanceof QlooClientError) {
+          if (cause.retryable && attempt < this.#maxAttempts) {
+            await this.#sleep(this.#retryDelay(attempt), options.signal);
+            continue;
+          }
+          throw cause;
+        }
+        if (timedOut) {
+          if (attempt < this.#maxAttempts) {
+            await this.#sleep(this.#retryDelay(attempt), options.signal);
+            continue;
+          }
+          throw new QlooClientError("QLOO_TIMEOUT", "Qloo API request timed out.", {
+            cause,
+            retryable: true
+          });
+        }
+        if (attempt < this.#maxAttempts) {
+          await this.#sleep(this.#retryDelay(attempt), options.signal);
+          continue;
+        }
+        const failure = classifyQlooNetworkFailure(cause);
+        throw new QlooClientError(failure.code, failure.message, {
+          cause,
+          retryable: failure.retryable,
+          details: {
+            kind: failure.kind,
+            attempts: this.#maxAttempts,
+            ...failure.systemCode ? { systemCode: failure.systemCode } : {}
+          }
+        });
+      } finally {
+        attemptSignal.dispose();
+      }
+      if (response.ok)
+        return body;
+      const retryable = RETRYABLE_STATUS_CODES.has(response.status);
+      if (retryable && attempt < this.#maxAttempts) {
+        const retryAfter = retryAfterMilliseconds(response);
+        await this.#sleep(Math.min(retryAfter ?? this.#retryDelay(attempt), this.#maxRetryDelayMs), options.signal);
+        continue;
+      }
+      throw new QlooClientError("QLOO_HTTP_ERROR", responseMessage(body, response), {
+        retryable,
+        details: body,
+        ...responseErrorMetadata(response)
+      });
+    }
+    throw new QlooClientError("QLOO_NETWORK_ERROR", "Unable to reach the Qloo API.", {
+      retryable: true
+    });
+  }
+  apiInformation(options) {
+    return this.get("/", {}, options);
+  }
+  insights(query, options) {
+    return this.get("/v2/insights", query, options);
+  }
+  searchEntities(query, options) {
+    return this.get("/search", query, options);
+  }
+  entities(entityIds, options) {
+    return this.get("/entities", { entity_ids: entityIds }, options);
+  }
+  audiences(query = {}, options) {
+    return this.get("/v2/audiences", query, options);
+  }
+  audienceTypes(query = {}, options) {
+    return this.get("/v2/audiences/types", query, options);
+  }
+  tags(query = {}, options) {
+    return this.get("/v2/tags", query, options);
+  }
+  tagTypes(query = {}, options) {
+    return this.get("/v2/tags/types", query, options);
+  }
+  compare(query, options) {
+    return this.get("/v2/analysis/compare", query, options);
+  }
+  trending(query, options) {
+    return this.get("/v2/trending", query, options);
+  }
+  #retryDelay(attempt) {
+    const exponential = 250 * 2 ** (attempt - 1);
+    const jittered = exponential * (0.75 + this.#random() * 0.5);
+    return Math.min(Math.round(jittered), this.#maxRetryDelayMs);
+  }
+};
+
+// packages/qloo-tool-schema/dist/upstream.lock.json
+var upstream_lock_default = {
+  lockVersion: 1,
+  source: {
+    documentationUrl: "https://docs.qloo.com",
+    registryUrl: "https://dash.readme.com/api/v1/api-registry/4svkj1svmrti5tfx",
+    registryId: "4svkj1svmrti5tfx",
+    retrievedAt: "2026-08-20",
+    apiTitle: "Qloo API",
+    apiVersion: "2.0",
+    openapiVersion: "3.1.0",
+    sha256: "da8d4b830f2a646815d25afcaa653f81f1ad939707e2e2560d2d0b9f103076f1"
+  },
+  expectations: {
+    productionServer: "https://api.qloo.com",
+    authentication: {
+      scheme: "ApiKey",
+      type: "apiKey",
+      location: "header",
+      header: "X-Api-Key"
+    },
+    getPaths: [
+      "/",
+      "/entities",
+      "/search",
+      "/v2/analysis/compare",
+      "/v2/audiences",
+      "/v2/audiences/types",
+      "/v2/insights",
+      "/v2/tags",
+      "/v2/tags/types",
+      "/v2/trending"
+    ]
+  },
+  documentedExceptions: [
+    {
+      value: "urn:demographics",
+      scope: "/v2/insights filter.type",
+      status: "documented-but-not-enumerated",
+      documentationUrl: "https://docs.qloo.com/reference/demographics-use-case",
+      treatment: "Preserve as an explicit documentation exception; do not synthesize an endpoint payload schema from it."
+    },
+    {
+      value: "urn:tag",
+      scope: "/v2/insights filter.type",
+      status: "documented-but-not-enumerated",
+      documentationUrl: "https://docs.qloo.com/reference/taste-analysis",
+      treatment: "The pinned specification mentions this value in diversify.by documentation but omits it from the filter.type enum; preserve the discrepancy for review."
+    }
+  ]
+};
+
+// packages/qloo-tool-schema/dist/src/catalog.js
+var QLOO_TOOL_CATALOG_VERSION = "1.0.0";
+var QLOO_TOOL_RESULT_SCHEMA_VERSION = "1.0-preview.1";
+var QLOO_WORKFLOW_OPERATION_IDS = [
+  "recommend",
+  "rank",
+  "describe",
+  "where_popular",
+  "compare_audiences",
+  "entity_tags",
+  "audience_demographics",
+  "trends",
+  "find_tags"
+];
+var QLOO_CAPABILITIES_TOOL_NAME = "qloo_capabilities";
+var QLOO_INSIGHTS_ENTITY_TYPES = [
+  { id: "artist", urn: "urn:entity:artist" },
+  { id: "book", urn: "urn:entity:book" },
+  { id: "brand", urn: "urn:entity:brand" },
+  { id: "movie", urn: "urn:entity:movie" },
+  { id: "person", urn: "urn:entity:person" },
+  { id: "place", urn: "urn:entity:place" },
+  { id: "podcast", urn: "urn:entity:podcast" },
+  { id: "tv_show", urn: "urn:entity:tv_show" },
+  { id: "videogame", urn: "urn:entity:videogame" }
+];
+var QLOO_SEARCH_ENTITY_TYPES = [
+  ...QLOO_INSIGHTS_ENTITY_TYPES,
+  { id: "locality", urn: "urn:entity:locality" },
+  { id: "actor", urn: "urn:entity:actor" },
+  { id: "album", urn: "urn:entity:album" },
+  { id: "author", urn: "urn:entity:author" },
+  { id: "director", urn: "urn:entity:director" }
+];
+function buildEntityTypeAliases(entityTypes) {
+  const aliases = /* @__PURE__ */ new Map();
+  const urnById = new Map(entityTypes.map(({ id, urn }) => [id, urn]));
+  for (const entityType of entityTypes) {
+    aliases.set(entityType.id, entityType.urn);
+    aliases.set(entityType.urn, entityType.urn);
+    aliases.set(`${entityType.id}s`, entityType.urn);
+  }
+  const addAlias = (alias, id) => {
+    const urn = urnById.get(id);
+    if (urn)
+      aliases.set(alias, urn);
+  };
+  addAlias("people", "person");
+  addAlias("localities", "locality");
+  addAlias("tv", "tv_show");
+  addAlias("show", "tv_show");
+  addAlias("shows", "tv_show");
+  addAlias("tv show", "tv_show");
+  addAlias("tv shows", "tv_show");
+  addAlias("game", "videogame");
+  addAlias("games", "videogame");
+  addAlias("video game", "videogame");
+  addAlias("video games", "videogame");
+  return aliases;
+}
+var insightsEntityTypeByAlias = buildEntityTypeAliases(QLOO_INSIGHTS_ENTITY_TYPES);
+var searchEntityTypeByAlias = buildEntityTypeAliases(QLOO_SEARCH_ENTITY_TYPES);
+function resolveQlooInsightsEntityType(value) {
+  return insightsEntityTypeByAlias.get(value.trim().toLowerCase());
+}
+function resolveQlooSearchEntityType(value) {
+  return searchEntityTypeByAlias.get(value.trim().toLowerCase());
+}
+var operationSummaries = {
+  recommend: "Find entities for a taste profile, audience, or collection of signals.",
+  rank: "Rank a supplied set of options for signals, location, or audience.",
+  describe: "Resolve and describe one Qloo entity.",
+  where_popular: "Find geographic areas where an entity has comparatively strong affinity.",
+  compare_audiences: "Contrast two signal groups and identify shared or differentiating affinities.",
+  entity_tags: "Retrieve concepts and tags that characterize entities.",
+  audience_demographics: "Retrieve aggregate audience segments associated with an entity.",
+  trends: "Retrieve interest or trend information over a time range.",
+  find_tags: "Search the Qloo tag ontology by natural-language concept."
+};
+var QLOO_WORKFLOW_OPERATIONS = Object.freeze(QLOO_WORKFLOW_OPERATION_IDS.map((id) => Object.freeze({
+  id,
+  toolName: `qloo_${id}`,
+  summary: operationSummaries[id],
+  since: QLOO_TOOL_CATALOG_VERSION
+})));
+var upstreamLock = upstream_lock_default;
+var upstreamGetPaths = Object.freeze([
+  ...upstreamLock.expectations.getPaths
+]);
+var documentedExceptions = Object.freeze(upstreamLock.documentedExceptions.map((exception) => Object.freeze({ ...exception })));
+var QLOO_CAPABILITIES_TOOL = Object.freeze({
+  name: QLOO_CAPABILITIES_TOOL_NAME,
+  description: "Return the versioned Qloo workflow catalog and pinned upstream API contract metadata without making a network request.",
+  inputSchema: Object.freeze({
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    type: "object",
+    additionalProperties: false,
+    properties: Object.freeze({
+      operation_ids: Object.freeze({
+        type: "array",
+        description: "Optional canonical operation IDs to include. Omit for the complete catalog.",
+        uniqueItems: true,
+        items: Object.freeze({
+          type: "string",
+          enum: QLOO_WORKFLOW_OPERATION_IDS
+        })
+      })
+    })
+  })
+});
+var operationIds = new Set(QLOO_WORKFLOW_OPERATION_IDS);
+function isQlooWorkflowOperationId(value) {
+  return operationIds.has(value);
+}
+function getQlooCapabilities(input = {}) {
+  const selected = input.operation_ids ? new Set(input.operation_ids) : void 0;
+  return {
+    contract_version: QLOO_TOOL_CATALOG_VERSION,
+    introspection_tool: QLOO_CAPABILITIES_TOOL_NAME,
+    operations: selected ? QLOO_WORKFLOW_OPERATIONS.filter(({ id }) => selected.has(id)) : QLOO_WORKFLOW_OPERATIONS,
+    upstream: {
+      documentation_url: upstreamLock.source.documentationUrl,
+      api_version: upstreamLock.source.apiVersion,
+      openapi_version: upstreamLock.source.openapiVersion,
+      production_server: upstreamLock.expectations.productionServer,
+      lock_sha256: upstreamLock.source.sha256,
+      get_paths: upstreamGetPaths,
+      documented_exceptions: documentedExceptions
+    }
+  };
+}
+
+// packages/qloo-tool-schema/dist/src/workflow-contracts.js
+import { Type } from "typebox";
+import { Value } from "typebox/value";
+var QLOO_TOOL_DEFAULT_LIMIT = 10;
+var QLOO_TOOL_MAX_RESULTS = 20;
+var QLOO_TAG_BOOLEAN_OPERATORS = ["union", "intersection"];
+var insightsEntityTypeIds = QLOO_INSIGHTS_ENTITY_TYPES.map(({ id }) => id);
+var searchEntityTypeIds = QLOO_SEARCH_ENTITY_TYPES.map(({ id }) => id);
+var QLOO_INSIGHTS_ENTITY_TYPE_SCHEMA = Type.String({
+  enum: insightsEntityTypeIds,
+  description: `Qloo Insights entity type: ${insightsEntityTypeIds.join(", ")}.`
+});
+var QLOO_SEARCH_ENTITY_TYPE_SCHEMA = Type.String({
+  enum: searchEntityTypeIds,
+  description: `Qloo search entity type: ${searchEntityTypeIds.join(", ")}.`
+});
+var QLOO_TAG_BOOLEAN_OPERATOR_SCHEMA = Type.String({
+  enum: QLOO_TAG_BOOLEAN_OPERATORS,
+  description: "Combine tag values with union (any) or intersection (all)."
+});
+var QLOO_LIMIT_SCHEMA = Type.Optional(Type.Integer({
+  minimum: 1,
+  maximum: QLOO_TOOL_MAX_RESULTS,
+  default: QLOO_TOOL_DEFAULT_LIMIT,
+  description: `Maximum results to return (1-${QLOO_TOOL_MAX_RESULTS}).`
+}));
+var QLOO_ENTITY_INPUTS_SCHEMA = Type.Array(Type.String({ minLength: 1 }), {
+  minItems: 1,
+  maxItems: 10,
+  description: "Entity names or Qloo entity UUIDs. Keep one combined taste profile in one call."
+});
+var QLOO_TAG_INPUTS_SCHEMA = Type.Array(Type.String({ minLength: 1 }), {
+  minItems: 1,
+  maxItems: 10,
+  description: "Natural-language tag concepts or stable Qloo tag URNs."
+});
+var QLOO_DEMOGRAPHIC_SCHEMA = Type.String({
+  minLength: 1,
+  description: "Audience demographic in natural language, such as 'young women', 'men 25-34', or 'millennials'. It is converted to documented Qloo demographic signals.",
+  examples: ["young women", "men 25-34", "millennials"]
+});
+var QLOO_REQUEST_PREVIEW_SCHEMA = Type.Object({
+  method: Type.Literal("GET"),
+  path: Type.String({ minLength: 1 }),
+  query: Type.Unknown()
+}, { additionalProperties: false });
+var QLOO_RESULT_ENVELOPE_SCHEMA = Type.Object({
+  schema_version: Type.Literal(QLOO_TOOL_RESULT_SCHEMA_VERSION),
+  operation: Type.String(),
+  status: Type.Union([
+    Type.Literal("ok"),
+    Type.Literal("empty"),
+    Type.Literal("needs_input"),
+    Type.Literal("partial"),
+    Type.Literal("degraded"),
+    Type.Literal("error")
+  ]),
+  summary: Type.Optional(Type.String()),
+  interpretation: Type.Optional(Type.Unknown()),
+  results: Type.Optional(Type.Unknown()),
+  result_count: Type.Optional(Type.Integer({ minimum: 0 })),
+  warnings: Type.Optional(Type.Array(Type.String())),
+  query_intent: Type.Optional(Type.Unknown()),
+  error: Type.Optional(Type.Object({
+    code: Type.String(),
+    layer: Type.String(),
+    retryable: Type.Boolean(),
+    recovery: Type.String()
+  }, { additionalProperties: false })),
+  execution: Type.Object({
+    transport: Type.String({ enum: ["direct", "cli", "mcp"] }),
+    transport_name: Type.String(),
+    correlation_id: Type.String(),
+    duration_ms: Type.Number({ minimum: 0 })
+  }, { additionalProperties: false }),
+  provenance: Type.Optional(Type.Object({
+    source: Type.String(),
+    endpoint: Type.String(),
+    documentation: Type.String(),
+    transport: Type.Optional(Type.String()),
+    requests: Type.Optional(Type.Array(QLOO_REQUEST_PREVIEW_SCHEMA, {
+      maxItems: 20
+    }))
+  }, { additionalProperties: false }))
+}, { additionalProperties: true });
+var QLOO_WORKFLOW_INPUT_SCHEMAS = {
+  recommend: Type.Object({
+    target_type: QLOO_INSIGHTS_ENTITY_TYPE_SCHEMA,
+    signals: Type.Optional(QLOO_ENTITY_INPUTS_SCHEMA),
+    signal_tags: Type.Optional(QLOO_TAG_INPUTS_SCHEMA),
+    signal_tags_operator: Type.Optional(QLOO_TAG_BOOLEAN_OPERATOR_SCHEMA),
+    signal_location: Type.Optional(Type.String({ minLength: 1 })),
+    demographic: Type.Optional(QLOO_DEMOGRAPHIC_SCHEMA),
+    filter_location: Type.Optional(Type.String({ minLength: 1 })),
+    include_tags: Type.Optional(QLOO_TAG_INPUTS_SCHEMA),
+    include_tags_operator: Type.Optional(QLOO_TAG_BOOLEAN_OPERATOR_SCHEMA),
+    exclude_tags: Type.Optional(QLOO_TAG_INPUTS_SCHEMA),
+    exclude_tags_operator: Type.Optional(QLOO_TAG_BOOLEAN_OPERATOR_SCHEMA),
+    explain: Type.Optional(Type.Boolean({ default: true })),
+    limit: QLOO_LIMIT_SCHEMA
+  }, { additionalProperties: false }),
+  rank: Type.Object({
+    options: QLOO_ENTITY_INPUTS_SCHEMA,
+    option_type: QLOO_INSIGHTS_ENTITY_TYPE_SCHEMA,
+    signals: Type.Optional(QLOO_ENTITY_INPUTS_SCHEMA),
+    signal_location: Type.Optional(Type.String({ minLength: 1 })),
+    demographic: Type.Optional(QLOO_DEMOGRAPHIC_SCHEMA),
+    include_tags: Type.Optional(QLOO_TAG_INPUTS_SCHEMA),
+    exclude_tags: Type.Optional(QLOO_TAG_INPUTS_SCHEMA)
+  }, { additionalProperties: false }),
+  describe: Type.Object({
+    entity: Type.String({ minLength: 1 }),
+    type: Type.Optional(QLOO_SEARCH_ENTITY_TYPE_SCHEMA)
+  }, { additionalProperties: false }),
+  where_popular: Type.Object({
+    entity: Type.String({ minLength: 1 }),
+    entity_type: Type.Optional(QLOO_SEARCH_ENTITY_TYPE_SCHEMA),
+    within: Type.String({
+      minLength: 1,
+      description: "Required geographic area that constrains the heatmap."
+    }),
+    limit: QLOO_LIMIT_SCHEMA
+  }, { additionalProperties: false }),
+  compare_audiences: Type.Object({
+    group_a: QLOO_ENTITY_INPUTS_SCHEMA,
+    group_b: QLOO_ENTITY_INPUTS_SCHEMA,
+    target_type: Type.Optional(QLOO_INSIGHTS_ENTITY_TYPE_SCHEMA),
+    limit: QLOO_LIMIT_SCHEMA
+  }, { additionalProperties: false }),
+  entity_tags: Type.Object({
+    entities: QLOO_ENTITY_INPUTS_SCHEMA,
+    entity_type: Type.Optional(QLOO_SEARCH_ENTITY_TYPE_SCHEMA),
+    limit: QLOO_LIMIT_SCHEMA
+  }, { additionalProperties: false }),
+  audience_demographics: Type.Object({
+    entity: Type.String({ minLength: 1 }),
+    entity_type: Type.Optional(QLOO_SEARCH_ENTITY_TYPE_SCHEMA),
+    limit: QLOO_LIMIT_SCHEMA
+  }, { additionalProperties: false }),
+  trends: Type.Object({
+    entities: Type.Array(Type.String({ minLength: 1 }), { minItems: 1, maxItems: 5 }),
+    entity_type: QLOO_INSIGHTS_ENTITY_TYPE_SCHEMA,
+    start_date: Type.String({
+      pattern: "^\\d{4}-\\d{2}-\\d{2}$",
+      description: "Inclusive start date in YYYY-MM-DD format."
+    }),
+    end_date: Type.String({
+      pattern: "^\\d{4}-\\d{2}-\\d{2}$",
+      description: "Inclusive end date in YYYY-MM-DD format."
+    }),
+    limit: QLOO_LIMIT_SCHEMA
+  }, { additionalProperties: false }),
+  find_tags: Type.Object({
+    query: Type.String({ minLength: 1 }),
+    semantic: Type.Optional(Type.Boolean({ default: true })),
+    limit: QLOO_LIMIT_SCHEMA
+  }, { additionalProperties: false })
+};
+var sharedWorkflowBehavior = Object.freeze({
+  readOnly: true,
+  idempotent: true,
+  mutating: false,
+  destructive: false,
+  openWorld: true,
+  concurrency: "safe_for_independent_inputs",
+  requiredCredential: "qloo_api",
+  defaultResultBudget: QLOO_TOOL_DEFAULT_LIMIT,
+  maximumResultBudget: QLOO_TOOL_MAX_RESULTS,
+  safeRetryClasses: Object.freeze(["dns", "connect", "timeout", "rate_limit", "upstream_5xx"]),
+  supportedTransports: Object.freeze(["direct", "mcp"])
+});
+var mediumLatencyOperations = /* @__PURE__ */ new Set([
+  "recommend",
+  "rank",
+  "compare_audiences",
+  "entity_tags",
+  "audience_demographics",
+  "trends"
+]);
+var QLOO_WORKFLOW_BEHAVIORS = Object.freeze(Object.fromEntries(Object.keys(QLOO_WORKFLOW_INPUT_SCHEMAS).map((operation) => [
+  operation,
+  Object.freeze({
+    ...sharedWorkflowBehavior,
+    expectedLatency: mediumLatencyOperations.has(operation) ? "medium" : "low"
+  })
+])));
+var QLOO_WORKFLOW_METADATA = {
+  recommend: {
+    toolName: "qloo_recommend",
+    label: "Qloo recommendations",
+    description: "Find Qloo entities related to one combined entity, tag, location, and demographic taste profile. Signals influence affinity; filters constrain output.",
+    promptSnippet: "Recommend entities from a combined Qloo taste profile",
+    promptGuidelines: [
+      "Pass every related taste and audience signal together in one qloo_recommend call.",
+      "Use signal_location for audience location and filter_location to constrain result geography.",
+      "Include demographic and location in the same call when both describe the audience."
+    ],
+    documentation: ["https://docs.qloo.com/reference/insights-api-deep-dive"]
+  },
+  rank: {
+    toolName: "qloo_rank",
+    label: "Qloo rank",
+    description: "Rank one supplied option set against one shared entity, location, demographic, and tag profile. Scores from separate calls are not comparable.",
+    promptSnippet: "Rank a caller-supplied shortlist with Qloo",
+    promptGuidelines: ["Pass every option in one qloo_rank call so scores remain comparable."],
+    documentation: ["https://docs.qloo.com/reference/insights-api-deep-dive"]
+  },
+  describe: {
+    toolName: "qloo_describe",
+    label: "Qloo entity",
+    description: "Resolve one named entity or Qloo UUID and return only metadata present in Qloo.",
+    promptSnippet: "Resolve and describe one Qloo entity",
+    documentation: ["https://docs.qloo.com/reference/get-search", "https://docs.qloo.com/reference/get-entities"]
+  },
+  where_popular: {
+    toolName: "qloo_where_popular",
+    label: "Qloo geographic affinity",
+    description: "Find geographic areas where one entity has strong query-relative affinity. This is distinct from filtering recommendations to a place.",
+    promptSnippet: "Find where an entity is comparatively popular",
+    documentation: ["https://docs.qloo.com/reference/heatmaps-use-case"]
+  },
+  compare_audiences: {
+    toolName: "qloo_compare_audiences",
+    label: "Qloo audience comparison",
+    description: "Compare two complete groups of entity signals in one Qloo analysis request.",
+    promptSnippet: "Compare two Qloo taste-signal groups",
+    documentation: ["https://docs.qloo.com/reference/analysis-compare"]
+  },
+  entity_tags: {
+    toolName: "qloo_entity_tags",
+    label: "Qloo entity tags",
+    description: "Retrieve Qloo concepts that jointly characterize one or more entities using the documented urn:tag Insights workflow.",
+    promptSnippet: "Find concepts that characterize Qloo entities",
+    documentation: ["https://docs.qloo.com/reference/taste-analysis"]
+  },
+  audience_demographics: {
+    toolName: "qloo_audience_demographics",
+    label: "Qloo audience demographics",
+    description: "Retrieve aggregate demographic distributions associated with one entity through the documented urn:demographics Insights workflow.",
+    promptSnippet: "Inspect aggregate demographics associated with a Qloo entity",
+    documentation: ["https://docs.qloo.com/reference/demographics-use-case"]
+  },
+  trends: {
+    toolName: "qloo_trends",
+    label: "Qloo trends",
+    description: "Retrieve Qloo time-series popularity metrics for one to five resolved entities over an ISO date range.",
+    promptSnippet: "Track Qloo entity popularity metrics over time",
+    documentation: ["https://docs.qloo.com/reference/get-trending"]
+  },
+  find_tags: {
+    toolName: "qloo_find_tags",
+    label: "Qloo tag search",
+    description: "Search Qloo's tag ontology by natural-language concept and return stable tag URNs.",
+    promptSnippet: "Search the Qloo tag ontology",
+    documentation: ["https://docs.qloo.com/reference/get-tags-1"]
+  }
+};
+var QLOO_WORKFLOW_CONTRACTS = Object.freeze(Object.fromEntries(Object.entries(QLOO_WORKFLOW_METADATA).map(([id, metadata]) => [
+  id,
+  Object.freeze({
+    id,
+    ...metadata,
+    behavior: QLOO_WORKFLOW_BEHAVIORS[id],
+    inputSchema: QLOO_WORKFLOW_INPUT_SCHEMAS[id],
+    resultSchema: QLOO_RESULT_ENVELOPE_SCHEMA
+  })
+])));
+var QLOO_ADAPTER_CONTRACT_MANIFEST_SCHEMA_VERSION = "1.1";
+function getQlooExecutableCapabilities(input = {}) {
+  const capabilities = getQlooCapabilities(input);
+  return {
+    ...capabilities,
+    result_schema_version: QLOO_TOOL_RESULT_SCHEMA_VERSION,
+    operations: capabilities.operations.map((operation) => {
+      const contract = QLOO_WORKFLOW_CONTRACTS[operation.id];
+      return {
+        ...operation,
+        input_schema: contract.inputSchema,
+        result_schema: contract.resultSchema,
+        documentation: contract.documentation,
+        behavior: contract.behavior
+      };
+    })
+  };
+}
+var QLOO_QUERY_INTENT_VERSION = "1.0-preview.1";
+function createQlooQueryIntent(operation, input) {
+  const base = {
+    schema_version: QLOO_QUERY_INTENT_VERSION,
+    source_contract_version: QLOO_TOOL_CATALOG_VERSION,
+    operation,
+    job: operation,
+    signals: {},
+    filters: {},
+    operators: {},
+    output: {},
+    assumptions: [],
+    unresolved: []
+  };
+  switch (operation) {
+    case "recommend": {
+      const value = input;
+      return {
+        ...base,
+        target: { type: value.target_type },
+        signals: {
+          ...value.signals ? { entities: value.signals } : {},
+          ...value.signal_tags ? { tags: value.signal_tags } : {},
+          ...value.signal_location ? { location: value.signal_location } : {},
+          ...value.demographic ? { demographic: value.demographic } : {}
+        },
+        filters: {
+          ...value.include_tags ? { includeTags: value.include_tags } : {},
+          ...value.exclude_tags ? { excludeTags: value.exclude_tags } : {},
+          ...value.filter_location ? { location: value.filter_location } : {}
+        },
+        operators: {
+          ...value.signal_tags ? { signalTags: value.signal_tags_operator ?? "intersection" } : {},
+          ...value.include_tags ? { includeTags: value.include_tags_operator ?? "union" } : {},
+          ...value.exclude_tags ? { excludeTags: value.exclude_tags_operator ?? "union" } : {}
+        },
+        output: { limit: value.limit ?? QLOO_TOOL_DEFAULT_LIMIT, explain: value.explain ?? true },
+        assumptions: [
+          ...value.limit === void 0 ? [`limit=${QLOO_TOOL_DEFAULT_LIMIT}`] : [],
+          ...value.explain === void 0 ? ["explain=true"] : []
+        ]
+      };
+    }
+    case "rank": {
+      const value = input;
+      return {
+        ...base,
+        target: { type: value.option_type },
+        signals: {
+          ...value.signals ? { entities: value.signals } : {},
+          ...value.signal_location ? { location: value.signal_location } : {},
+          ...value.demographic ? { demographic: value.demographic } : {}
+        },
+        filters: {
+          candidateEntities: value.options,
+          ...value.include_tags ? { includeTags: value.include_tags } : {},
+          ...value.exclude_tags ? { excludeTags: value.exclude_tags } : {}
+        },
+        operators: {
+          ...value.include_tags ? { includeTags: "union" } : {},
+          ...value.exclude_tags ? { excludeTags: "union" } : {}
+        },
+        output: { limit: value.options.length },
+        assumptions: []
+      };
+    }
+    case "describe": {
+      const value = input;
+      return { ...base, target: { ...value.type ? { type: value.type } : {}, entities: [value.entity] } };
+    }
+    case "where_popular": {
+      const value = input;
+      return {
+        ...base,
+        target: { ...value.entity_type ? { type: value.entity_type } : {}, entities: [value.entity] },
+        filters: { location: value.within },
+        output: { limit: value.limit ?? QLOO_TOOL_DEFAULT_LIMIT },
+        assumptions: value.limit === void 0 ? [`limit=${QLOO_TOOL_DEFAULT_LIMIT}`] : []
+      };
+    }
+    case "compare_audiences": {
+      const value = input;
+      return {
+        ...base,
+        ...value.target_type ? { target: { type: value.target_type } } : {},
+        signals: { groups: [value.group_a, value.group_b] },
+        output: { limit: value.limit ?? QLOO_TOOL_DEFAULT_LIMIT },
+        assumptions: value.limit === void 0 ? [`limit=${QLOO_TOOL_DEFAULT_LIMIT}`] : []
+      };
+    }
+    case "entity_tags": {
+      const value = input;
+      return {
+        ...base,
+        ...value.entity_type ? { target: { type: value.entity_type } } : {},
+        signals: { entities: value.entities },
+        output: { limit: value.limit ?? QLOO_TOOL_DEFAULT_LIMIT },
+        assumptions: value.limit === void 0 ? [`limit=${QLOO_TOOL_DEFAULT_LIMIT}`] : []
+      };
+    }
+    case "audience_demographics": {
+      const value = input;
+      return {
+        ...base,
+        target: value.entity_type ? { type: value.entity_type, entities: [value.entity] } : { entities: [value.entity] },
+        output: { limit: value.limit ?? QLOO_TOOL_DEFAULT_LIMIT },
+        assumptions: value.limit === void 0 ? [`limit=${QLOO_TOOL_DEFAULT_LIMIT}`] : []
+      };
+    }
+    case "trends": {
+      const value = input;
+      return {
+        ...base,
+        target: { type: value.entity_type, entities: value.entities },
+        filters: { startDate: value.start_date, endDate: value.end_date },
+        output: { limit: value.limit ?? QLOO_TOOL_DEFAULT_LIMIT },
+        assumptions: value.limit === void 0 ? [`limit=${QLOO_TOOL_DEFAULT_LIMIT}`] : []
+      };
+    }
+    case "find_tags": {
+      const value = input;
+      return {
+        ...base,
+        target: { concept: value.query },
+        output: { limit: value.limit ?? QLOO_TOOL_DEFAULT_LIMIT },
+        assumptions: [
+          ...value.semantic === void 0 ? ["semantic=true"] : [],
+          ...value.limit === void 0 ? [`limit=${QLOO_TOOL_DEFAULT_LIMIT}`] : []
+        ]
+      };
+    }
+  }
+}
+function ageBucketsForRange(low, high) {
+  const ranges = [
+    [0, 24, "24_and_younger"],
+    [25, 29, "25_to_29"],
+    [30, 34, "30_to_34"],
+    [35, 44, "35_to_44"],
+    [45, 54, "45_to_54"],
+    [55, 120, "55_and_older"]
+  ];
+  const matches = ranges.filter(([bucketLow, bucketHigh]) => low <= bucketHigh && high >= bucketLow).map(([, , name]) => name);
+  return matches.join(",");
+}
+function parseQlooDemographic(value) {
+  const normalized = value.normalize("NFKC").trim().toLocaleLowerCase("en-US");
+  const result = {};
+  if (/\b(women|woman|female|ladies)\b/u.test(normalized))
+    result.gender = "female";
+  else if (/\b(men|man|male|guys)\b/u.test(normalized))
+    result.gender = "male";
+  const explicitRange = normalized.match(/\b(\d{1,2})\s*(?:-|–|to)\s*(\d{1,2})\b/u);
+  if (explicitRange) {
+    const low = Number(explicitRange[1]);
+    const high = Number(explicitRange[2]);
+    if (low <= high)
+      result.age = ageBucketsForRange(low, high);
+  } else if (/\b(teenagers?|teens?|gen[\s-]?z)\b/u.test(normalized)) {
+    result.age = "24_and_younger";
+  } else if (/\byoung\b/u.test(normalized)) {
+    result.age = "24_and_younger,25_to_29";
+  } else if (/\bmillennials?\b/u.test(normalized)) {
+    result.age = "30_to_34,35_to_44";
+  } else if (/\b(seniors?|elderly|retirees?)\b/u.test(normalized)) {
+    result.age = "55_and_older";
+  } else if (/\bmiddle[\s-]?aged?\b/u.test(normalized)) {
+    result.age = "35_to_44,45_to_54";
+  } else {
+    const over = normalized.match(/\b(?:over|older than|above)\s*(\d{1,2})\b/u);
+    const under = normalized.match(/\b(?:under|younger than|below)\s*(\d{1,2})\b/u);
+    if (over)
+      result.age = ageBucketsForRange(Number(over[1]), 120);
+    else if (under)
+      result.age = ageBucketsForRange(0, Number(under[1]));
+  }
+  return result;
+}
+
+// packages/qloo-tool-schema/dist/src/resolution-contracts.js
+import { Type as Type2 } from "typebox";
+var QLOO_RESOLUTION_CONTRACT_VERSION = "1.0-preview.1";
+var QLOO_RESOLUTION_PROVIDER_DESCRIPTOR_SCHEMA = Type2.Object({
+  contract_version: Type2.Literal(QLOO_RESOLUTION_CONTRACT_VERSION),
+  provider_id: Type2.String({ minLength: 1 }),
+  name: Type2.String({ minLength: 1 }),
+  entity_strategy: Type2.String({ minLength: 1 }),
+  tag_strategy: Type2.String({ minLength: 1 }),
+  remote: Type2.Boolean(),
+  uses_model: Type2.Boolean(),
+  fallback: Type2.Literal("none")
+}, { additionalProperties: false });
+var QLOO_RESOLUTION_CANDIDATE_SCHEMA = Type2.Object({
+  id: Type2.String({ minLength: 1 }),
+  name: Type2.String({ minLength: 1 }),
+  type: Type2.Optional(Type2.String({ minLength: 1 })),
+  rank: Type2.Optional(Type2.Integer({ minimum: 1 })),
+  score: Type2.Optional(Type2.Number()),
+  popularity: Type2.Optional(Type2.Number()),
+  parent_types: Type2.Optional(Type2.Array(Type2.String({ minLength: 1 }), {
+    maxItems: 20,
+    uniqueItems: true
+  })),
+  description: Type2.Optional(Type2.String({ minLength: 1, maxLength: 500 })),
+  release_year: Type2.Optional(Type2.Integer()),
+  address: Type2.Optional(Type2.Unknown())
+}, { additionalProperties: false });
+var QLOO_RESOLUTION_PROVENANCE_SCHEMA = Type2.Object({
+  contract_version: Type2.Literal(QLOO_RESOLUTION_CONTRACT_VERSION),
+  provider_id: Type2.String({ minLength: 1 }),
+  provider_name: Type2.String({ minLength: 1 }),
+  endpoint: Type2.String({ minLength: 1 }),
+  strategy: Type2.String({ minLength: 1 }),
+  remote: Type2.Boolean(),
+  uses_model: Type2.Boolean(),
+  provider_version: Type2.Optional(Type2.String({ minLength: 1 })),
+  cache_status: Type2.Optional(Type2.String({ minLength: 1 }))
+}, { additionalProperties: false });
+var QLOO_RESOLUTION_OUTCOME_COMMON_SCHEMA = {
+  input: Type2.String({ minLength: 1 }),
+  provenance: QLOO_RESOLUTION_PROVENANCE_SCHEMA,
+  warnings: Type2.Optional(Type2.Array(Type2.String()))
+};
+var QLOO_RESOLUTION_OUTCOME_SCHEMA = Type2.Union([
+  Type2.Object({
+    ...QLOO_RESOLUTION_OUTCOME_COMMON_SCHEMA,
+    status: Type2.Literal("resolved"),
+    match: Type2.Union([
+      Type2.Literal("identifier"),
+      Type2.Literal("exact"),
+      Type2.Literal("semantic")
+    ]),
+    selected: QLOO_RESOLUTION_CANDIDATE_SCHEMA,
+    alternatives: Type2.Optional(Type2.Array(QLOO_RESOLUTION_CANDIDATE_SCHEMA))
+  }, { additionalProperties: false }),
+  Type2.Object({
+    ...QLOO_RESOLUTION_OUTCOME_COMMON_SCHEMA,
+    status: Type2.Literal("ambiguous"),
+    candidates: Type2.Array(QLOO_RESOLUTION_CANDIDATE_SCHEMA)
+  }, { additionalProperties: false }),
+  Type2.Object({
+    ...QLOO_RESOLUTION_OUTCOME_COMMON_SCHEMA,
+    status: Type2.Literal("not_found"),
+    candidates: Type2.Optional(Type2.Array(QLOO_RESOLUTION_CANDIDATE_SCHEMA))
+  }, { additionalProperties: false })
+]);
+
+// apps/qloo-harness/dist/qloo-tools.js
+import { Type as Type3 } from "typebox";
+import { createDelegatingQlooWorkflowExecutor, QlooWorkflowExecutionError } from "./workflow-executor.js";
+import { createFileExecutionObserver } from "./observability.js";
+import { resolveQlooPaths } from "./paths.js";
+import { createQlooCallComponent, createQlooResultComponent } from "./qloo-presentation.js";
+import { createPublicQlooResolutionProvider, createQlooResolutionProviderFromEnvironment } from "./resolution-provider.js";
+function defineTool(tool) {
+  return tool;
+}
+var DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+var DEFAULT_LIMIT = QLOO_TOOL_DEFAULT_LIMIT;
+var MAX_TOOL_RESULTS = QLOO_TOOL_MAX_RESULTS;
+var insightsEntityTypeIds2 = QLOO_INSIGHTS_ENTITY_TYPES.map(({ id }) => id);
+var searchEntityTypeIds2 = QLOO_SEARCH_ENTITY_TYPES.map(({ id }) => id);
+var runtimeInfoByTool = /* @__PURE__ */ new WeakMap();
+function associateRuntimeInfo(tools, executor) {
+  const info = executor ? {
+    transport: executor.transport.kind,
+    transportName: executor.transport.name,
+    remote: executor.transport.remote ?? false,
+    fallback: "none",
+    ...executor.resolution ? { resolution: executor.resolution } : {}
+  } : {
+    transport: "none",
+    transportName: "Qloo API unavailable",
+    remote: false,
+    fallback: "none"
+  };
+  for (const tool of tools)
+    runtimeInfoByTool.set(tool, info);
+  return [...tools];
+}
+function getQlooToolRuntimeInfo(tools) {
+  for (const tool of tools) {
+    const info = runtimeInfoByTool.get(tool);
+    if (info)
+      return info;
+  }
+  return void 0;
+}
+function requestOptions(signal, correlationId) {
+  return {
+    ...signal ? { signal } : {},
+    correlationId
+  };
+}
+function asRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+function asArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+function resultValue(response, key) {
+  const results = response.results;
+  if (Array.isArray(results))
+    return results;
+  return asRecord(results)?.[key] ?? results ?? [];
+}
+function resultArray(response, key) {
+  return asArray(resultValue(response, key));
+}
+function scalar(record, ...keys) {
+  for (const key of keys) {
+    if (record[key] !== void 0 && record[key] !== null)
+      return record[key];
+  }
+  return void 0;
+}
+function boundedValue(value, depth = 0) {
+  if (typeof value === "string")
+    return value.length > 2e3 ? `${value.slice(0, 2e3)}\u2026` : value;
+  if (typeof value === "number" || typeof value === "boolean" || value === null)
+    return value;
+  if (depth >= 5)
+    return "[detail omitted]";
+  if (Array.isArray(value))
+    return value.slice(0, MAX_TOOL_RESULTS).map((item) => boundedValue(item, depth + 1));
+  const record = asRecord(value);
+  if (!record)
+    return void 0;
+  return Object.fromEntries(Object.entries(record).slice(0, 40).map(([key, item]) => [key, boundedValue(item, depth + 1)]));
+}
+function compactEntity(value) {
+  const entity = asRecord(value);
+  if (!entity)
+    return void 0;
+  const properties = asRecord(entity.properties);
+  const query = asRecord(entity.query);
+  const explainability = boundedValue(query?.explainability);
+  const compactProperties = properties ? Object.fromEntries([
+    "description",
+    "short_description",
+    "release_year",
+    "release_date",
+    "content_rating",
+    "duration",
+    "image",
+    "geocode",
+    "address",
+    "price_level",
+    "business_rating"
+  ].flatMap((key) => properties[key] === void 0 ? [] : [[key, boundedValue(properties[key])]])) : void 0;
+  return {
+    entity_id: scalar(entity, "entity_id", "id"),
+    name: entity.name,
+    type: entity.type,
+    subtype: entity.subtype,
+    popularity: entity.popularity,
+    affinity: scalar(entity, "affinity") ?? query?.affinity,
+    ...explainability !== void 0 ? { explainability } : {},
+    ...compactProperties && Object.keys(compactProperties).length > 0 ? { properties: compactProperties } : {}
+  };
+}
+function compactTag(value) {
+  const tag = asRecord(value);
+  if (!tag)
+    return void 0;
+  const query = asRecord(tag.query);
+  return {
+    id: scalar(tag, "id", "tag_id"),
+    name: tag.name,
+    type: scalar(tag, "type", "subtype"),
+    popularity: tag.popularity,
+    affinity: tag.affinity ?? query?.affinity
+  };
+}
+function isCalendarDate(value) {
+  if (!DATE_PATTERN.test(value))
+    return false;
+  const [year, month, day] = value.split("-").map(Number);
+  if (year === void 0 || month === void 0 || day === void 0)
+    return false;
+  if (month < 1 || month > 12 || day < 1)
+    return false;
+  const leapYear = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+  const daysInMonth = [31, leapYear ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+  return day <= (daysInMonth[month - 1] ?? 0);
+}
+function heatmapAffinity(value) {
+  const query = asRecord(asRecord(value)?.query);
+  return typeof query?.affinity === "number" ? query.affinity : Number.NEGATIVE_INFINITY;
+}
+function interpretedEntity(entity) {
+  return {
+    input: entity.input,
+    entityId: entity.entityId,
+    name: entity.name,
+    ...entity.type ? { type: entity.type } : {},
+    match: entity.match,
+    ...entity.score !== void 0 ? { score: entity.score } : {}
+  };
+}
+function interpretedEntities(entities) {
+  return entities.map(interpretedEntity);
+}
+async function resolveEntities(provider, inputs, type, signal, correlationId) {
+  const { outcomes } = await provider.resolveEntities({
+    inputs,
+    ...type ? { type } : {}
+  }, {
+    ...signal ? { signal } : {},
+    correlationId
+  });
+  return {
+    resolved: outcomes.flatMap((outcome) => outcome.status === "resolved" ? [{
+      input: outcome.input,
+      entityId: outcome.selected.id,
+      name: outcome.selected.name,
+      ...outcome.selected.type ? { type: outcome.selected.type } : {},
+      match: outcome.match,
+      ...outcome.selected.score !== void 0 ? { score: outcome.selected.score } : {},
+      provenance: outcome.provenance
+    }] : []),
+    issues: outcomes.flatMap((outcome) => outcome.status === "resolved" ? [] : [{
+      input: outcome.input,
+      kind: outcome.status,
+      ...outcome.candidates ? {
+        candidates: outcome.candidates.map((candidate) => ({ ...candidate }))
+      } : {},
+      provenance: outcome.provenance,
+      ...outcome.warnings ? { warnings: outcome.warnings } : {}
+    }]),
+    outcomes
+  };
+}
+function interpretedTags(tags) {
+  return tags.map((tag) => ({
+    input: tag.input,
+    tagId: tag.tagId,
+    name: tag.name,
+    match: tag.match,
+    ...tag.score !== void 0 ? { score: tag.score } : {}
+  }));
+}
+async function resolveTags(provider, inputs, targetType, purpose, signal, correlationId) {
+  const { outcomes } = await provider.resolveTags({
+    inputs,
+    ...targetType ? { targetType } : {},
+    purpose
+  }, {
+    ...signal ? { signal } : {},
+    correlationId
+  });
+  return {
+    resolved: outcomes.flatMap((outcome) => outcome.status === "resolved" ? [{
+      input: outcome.input,
+      tagId: outcome.selected.id,
+      name: outcome.selected.name,
+      match: outcome.match,
+      ...outcome.selected.score !== void 0 ? { score: outcome.selected.score } : {},
+      ...outcome.alternatives ? {
+        alternatives: outcome.alternatives.map((candidate) => ({ ...candidate }))
+      } : {},
+      provenance: outcome.provenance,
+      ...outcome.warnings ? { warnings: outcome.warnings } : {}
+    }] : []),
+    issues: outcomes.flatMap((outcome) => outcome.status === "resolved" ? [] : [{
+      input: outcome.input,
+      kind: outcome.status,
+      ...outcome.candidates ? {
+        candidates: outcome.candidates.map((candidate) => ({ ...candidate }))
+      } : {},
+      provenance: outcome.provenance,
+      ...outcome.warnings ? { warnings: outcome.warnings } : {}
+    }]),
+    outcomes
+  };
+}
+function resolutionWarnings(...sets) {
+  return [...new Set(sets.flatMap(({ outcomes }) => outcomes.flatMap(({ warnings }) => warnings ?? [])))];
+}
+function resolutionReport(provider, ...sets) {
+  const warnings = resolutionWarnings(...sets);
+  return {
+    contract_version: provider.descriptor.contract_version,
+    provider: provider.descriptor,
+    outcomes: sets.flatMap(({ outcomes }) => outcomes),
+    ...warnings.length > 0 ? { warnings } : {}
+  };
+}
+function resolutionOutput(provider, ...sets) {
+  const warnings = resolutionWarnings(...sets);
+  return {
+    resolution: resolutionReport(provider, ...sets),
+    ...warnings.length > 0 ? { warnings } : {}
+  };
+}
+function resolveInsightsType(value) {
+  const resolved = resolveQlooInsightsEntityType(value);
+  if (!resolved) {
+    throw new Error(`Unsupported Qloo Insights type "${value}". Choose: ${insightsEntityTypeIds2.join(", ")}.`);
+  }
+  return resolved;
+}
+function resolveSearchType(value) {
+  const resolved = resolveQlooSearchEntityType(value);
+  if (!resolved) {
+    throw new Error(`Unsupported Qloo search type "${value}". Choose: ${searchEntityTypeIds2.join(", ")}.`);
+  }
+  return resolved;
+}
+function requireClient(client) {
+  if (!client) {
+    throw new Error("Live Qloo tools require Qloo authentication. Run `qloo setup` for guided configuration.");
+  }
+  return client;
+}
+function requireResolutionProvider(provider) {
+  if (!provider) {
+    throw new Error("Live Qloo tools require an explicit resolution provider.");
+  }
+  return provider;
+}
+function output(operation, payload) {
+  const result = {
+    schema_version: QLOO_TOOL_RESULT_SCHEMA_VERSION,
+    operation,
+    ...payload
+  };
+  return {
+    content: [{ type: "text", text: JSON.stringify(result) }],
+    details: result
+  };
+}
+function needsInput(operation, issues, message) {
+  return output(operation, {
+    status: "needs_input",
+    summary: message,
+    resolution: { issues },
+    results: []
+  });
+}
+function provenance(endpoint, docs, queries) {
+  return {
+    source: "Qloo API",
+    endpoint,
+    documentation: `https://docs.qloo.com/reference/${docs}`,
+    requests: queries.slice(0, 20).map((query) => ({
+      method: "GET",
+      path: endpoint,
+      query: boundedValue(query)
+    }))
+  };
+}
+function makeCapabilitiesTool(executor) {
+  return defineTool({
+    name: QLOO_CAPABILITIES_TOOL_NAME,
+    label: "Qloo capabilities",
+    description: "Inspect the local, versioned Qloo workflow catalog and pinned API source. Makes no network request.",
+    promptSnippet: "Inspect supported Qloo workflows and authoritative contract metadata",
+    parameters: Type3.Object({
+      operation_ids: Type3.Optional(Type3.Array(Type3.String({
+        enum: QLOO_WORKFLOW_OPERATION_IDS
+      }), { uniqueItems: true }))
+    }, { additionalProperties: false }),
+    async execute(_toolCallId, params) {
+      const operationIds2 = params.operation_ids?.filter(isQlooWorkflowOperationId);
+      return output("capabilities", {
+        manifest_schema_version: QLOO_ADAPTER_CONTRACT_MANIFEST_SCHEMA_VERSION,
+        ...getQlooExecutableCapabilities(operationIds2 === void 0 ? {} : { operation_ids: operationIds2 }),
+        adapter: {
+          id: "qloo_harness",
+          compatibility: "native",
+          canonical_workflow_execution: Boolean(executor),
+          supported_operation_ids: executor ? QLOO_WORKFLOW_OPERATION_IDS : [],
+          capabilities_tool: QLOO_CAPABILITIES_TOOL_NAME
+        },
+        execution_policy: executor ? {
+          active_transport: executor.transport.kind,
+          transport_name: executor.transport.name,
+          remote: executor.transport.remote ?? false,
+          fallback: "none",
+          ...executor.resolution ? { resolution: executor.resolution } : {}
+        } : {
+          active_transport: "none",
+          fallback: "none",
+          reason: "Qloo API authentication is unavailable."
+        }
+      });
+    }
+  });
+}
+function makeRecommendTool(clientOption, resolutionProviderOption) {
+  const contract = QLOO_WORKFLOW_CONTRACTS.recommend;
+  return defineTool({
+    name: contract.toolName,
+    label: contract.label,
+    description: contract.description,
+    promptSnippet: contract.promptSnippet,
+    promptGuidelines: [...contract.promptGuidelines],
+    parameters: contract.inputSchema,
+    async execute(toolCallId, params, signal) {
+      const client = requireClient(clientOption);
+      const resolutionProvider = requireResolutionProvider(resolutionProviderOption);
+      const targetType = resolveInsightsType(params.target_type);
+      const demographic = params.demographic ? parseQlooDemographic(params.demographic) : void 0;
+      if (params.demographic && !demographic?.gender && !demographic?.age) {
+        return needsInput("recommend", [], `Could not map demographic "${params.demographic}" to Qloo age or gender signals. Use a phrase such as "young women" or "men 25-34".`);
+      }
+      if (demographic && !params.signal_location) {
+        return needsInput("recommend", [], "Demographic Qloo signals require signal_location so the audience geography is explicit.");
+      }
+      if ((params.signals?.length ?? 0) === 0 && (params.signal_tags?.length ?? 0) === 0 && !params.signal_location && !demographic) {
+        return needsInput("recommend", [], "Provide at least one entity, tag, location, or demographic taste signal.");
+      }
+      const [entities, signalTags, includeTags, excludeTags] = await Promise.all([
+        resolveEntities(resolutionProvider, params.signals ?? [], void 0, signal, toolCallId),
+        resolveTags(resolutionProvider, params.signal_tags ?? [], targetType, "signal", signal, toolCallId),
+        resolveTags(resolutionProvider, params.include_tags ?? [], targetType, "include_filter", signal, toolCallId),
+        resolveTags(resolutionProvider, params.exclude_tags ?? [], targetType, "exclude_filter", signal, toolCallId)
+      ]);
+      const issues = [...entities.issues, ...signalTags.issues, ...includeTags.issues, ...excludeTags.issues];
+      if (issues.length > 0)
+        return needsInput("recommend", issues, "Choose or correct the unresolved Qloo inputs.");
+      const query = {
+        "filter.type": targetType,
+        take: params.limit ?? DEFAULT_LIMIT
+      };
+      if (entities.resolved.length > 0)
+        query["signal.interests.entities"] = entities.resolved.map(({ entityId }) => entityId);
+      if (signalTags.resolved.length > 0) {
+        query["signal.interests.tags"] = signalTags.resolved.map(({ tagId }) => tagId);
+        query["operator.signal.interests.tags"] = params.signal_tags_operator ?? "intersection";
+      }
+      if (params.signal_location)
+        query["signal.location.query"] = params.signal_location;
+      if (demographic?.gender)
+        query["signal.demographics.gender"] = demographic.gender;
+      if (demographic?.age)
+        query["signal.demographics.age"] = demographic.age;
+      if (params.filter_location)
+        query["filter.location.query"] = params.filter_location;
+      if (includeTags.resolved.length > 0) {
+        query["filter.tags"] = includeTags.resolved.map(({ tagId }) => tagId);
+        query["operator.filter.tags"] = params.include_tags_operator ?? "union";
+      }
+      if (excludeTags.resolved.length > 0) {
+        query["filter.exclude.tags"] = excludeTags.resolved.map(({ tagId }) => tagId);
+        query["operator.filter.exclude.tags"] = params.exclude_tags_operator ?? "union";
+      }
+      if (params.explain ?? true)
+        query["feature.explainability"] = true;
+      const response = await client.insights(query, requestOptions(signal, toolCallId));
+      const results = resultArray(response, "entities").map(compactEntity).filter((entity) => entity !== void 0).slice(0, params.limit ?? DEFAULT_LIMIT);
+      const explainability = boundedValue(asRecord(response.query)?.explainability);
+      return output("recommend", {
+        status: "ok",
+        interpretation: {
+          target_type: targetType,
+          signals: interpretedEntities(entities.resolved),
+          signal_tags: interpretedTags(signalTags.resolved),
+          signal_tags_operator: signalTags.resolved.length > 0 ? params.signal_tags_operator ?? "intersection" : void 0,
+          signal_location: params.signal_location,
+          demographic: params.demographic ? { input: params.demographic, ...demographic } : void 0,
+          filter_location: params.filter_location,
+          include_tags: interpretedTags(includeTags.resolved),
+          include_tags_operator: includeTags.resolved.length > 0 ? params.include_tags_operator ?? "union" : void 0,
+          exclude_tags: interpretedTags(excludeTags.resolved),
+          exclude_tags_operator: excludeTags.resolved.length > 0 ? params.exclude_tags_operator ?? "union" : void 0
+        },
+        ...resolutionOutput(resolutionProvider, entities, signalTags, includeTags, excludeTags),
+        results,
+        result_count: results.length,
+        ...explainability !== void 0 ? { explainability } : {},
+        provenance: provenance("/v2/insights", "insights-api-deep-dive", [query])
+      });
+    }
+  });
+}
+function makeRankTool(clientOption, resolutionProviderOption) {
+  const contract = QLOO_WORKFLOW_CONTRACTS.rank;
+  return defineTool({
+    name: contract.toolName,
+    label: contract.label,
+    description: contract.description,
+    promptSnippet: contract.promptSnippet,
+    promptGuidelines: [...contract.promptGuidelines],
+    parameters: contract.inputSchema,
+    async execute(toolCallId, params, signal) {
+      const client = requireClient(clientOption);
+      const resolutionProvider = requireResolutionProvider(resolutionProviderOption);
+      const targetType = resolveInsightsType(params.option_type);
+      const demographic = params.demographic ? parseQlooDemographic(params.demographic) : void 0;
+      if (params.demographic && !demographic?.gender && !demographic?.age) {
+        return needsInput("rank", [], `Could not map demographic "${params.demographic}" to Qloo age or gender signals.`);
+      }
+      if (demographic && !params.signal_location) {
+        return needsInput("rank", [], "Demographic Qloo signals require signal_location so the audience geography is explicit.");
+      }
+      if ((params.signals?.length ?? 0) === 0 && !params.signal_location && !demographic) {
+        return needsInput("rank", [], "Ranking requires an entity, location, or demographic signal.");
+      }
+      const [options, signals, includeTags, excludeTags] = await Promise.all([
+        resolveEntities(resolutionProvider, params.options, targetType, signal, toolCallId),
+        resolveEntities(resolutionProvider, params.signals ?? [], void 0, signal, toolCallId),
+        resolveTags(resolutionProvider, params.include_tags ?? [], targetType, "include_filter", signal, toolCallId),
+        resolveTags(resolutionProvider, params.exclude_tags ?? [], targetType, "exclude_filter", signal, toolCallId)
+      ]);
+      const issues = [...options.issues, ...signals.issues, ...includeTags.issues, ...excludeTags.issues];
+      if (issues.length > 0)
+        return needsInput("rank", issues, "Choose or correct the unresolved ranking inputs.");
+      const query = {
+        "filter.type": targetType,
+        "filter.results.entities": options.resolved.map(({ entityId }) => entityId),
+        take: options.resolved.length
+      };
+      if (signals.resolved.length > 0)
+        query["signal.interests.entities"] = signals.resolved.map(({ entityId }) => entityId);
+      if (params.signal_location)
+        query["signal.location.query"] = params.signal_location;
+      if (demographic?.gender)
+        query["signal.demographics.gender"] = demographic.gender;
+      if (demographic?.age)
+        query["signal.demographics.age"] = demographic.age;
+      if (includeTags.resolved.length > 0) {
+        query["filter.tags"] = includeTags.resolved.map(({ tagId }) => tagId);
+        query["operator.filter.tags"] = "union";
+      }
+      if (excludeTags.resolved.length > 0) {
+        query["filter.exclude.tags"] = excludeTags.resolved.map(({ tagId }) => tagId);
+        query["operator.filter.exclude.tags"] = "union";
+      }
+      const response = await client.insights(query, requestOptions(signal, toolCallId));
+      const results = resultArray(response, "entities").map(compactEntity).filter((entity) => entity !== void 0).slice(0, options.resolved.length);
+      return output("rank", {
+        status: "ok",
+        interpretation: {
+          option_type: targetType,
+          options: interpretedEntities(options.resolved),
+          signals: interpretedEntities(signals.resolved),
+          signal_location: params.signal_location,
+          demographic: params.demographic ? { input: params.demographic, ...demographic } : void 0,
+          include_tags: interpretedTags(includeTags.resolved),
+          exclude_tags: interpretedTags(excludeTags.resolved)
+        },
+        ...resolutionOutput(resolutionProvider, options, signals, includeTags, excludeTags),
+        results,
+        result_count: results.length,
+        provenance: provenance("/v2/insights", "insights-api-deep-dive", [query])
+      });
+    }
+  });
+}
+function makeDescribeTool(clientOption, resolutionProviderOption) {
+  const contract = QLOO_WORKFLOW_CONTRACTS.describe;
+  return defineTool({
+    name: contract.toolName,
+    label: contract.label,
+    description: contract.description,
+    promptSnippet: contract.promptSnippet,
+    parameters: contract.inputSchema,
+    async execute(toolCallId, params, signal) {
+      const client = requireClient(clientOption);
+      const resolutionProvider = requireResolutionProvider(resolutionProviderOption);
+      const type = params.type ? resolveSearchType(params.type) : void 0;
+      const resolution = await resolveEntities(resolutionProvider, [params.entity], type, signal, toolCallId);
+      if (resolution.issues.length > 0)
+        return needsInput("describe", resolution.issues, "Choose the intended Qloo entity.");
+      const needsDetailHydration = resolution.resolved.some(({ match }) => match !== "identifier");
+      const detailedResults = needsDetailHydration ? resultArray(await client.entities(resolution.resolved.map(({ entityId }) => entityId), requestOptions(signal, toolCallId)), "entities").map(compactEntity).filter((entity) => entity !== void 0) : [];
+      const results = detailedResults.length > 0 ? detailedResults : resolution.resolved.map((entity) => ({
+        entity_id: entity.entityId,
+        name: entity.name,
+        type: entity.type
+      }));
+      return output("describe", {
+        status: results.length > 0 ? "ok" : "empty",
+        interpretation: {
+          entity: resolution.resolved[0] ? interpretedEntity(resolution.resolved[0]) : void 0
+        },
+        ...resolutionOutput(resolutionProvider, resolution),
+        results,
+        result_count: results.length,
+        provenance: provenance("/entities", "get-entities", [{
+          entity_ids: resolution.resolved.map(({ entityId }) => entityId)
+        }])
+      });
+    }
+  });
+}
+function makeWherePopularTool(clientOption, resolutionProviderOption) {
+  const contract = QLOO_WORKFLOW_CONTRACTS.where_popular;
+  return defineTool({
+    name: contract.toolName,
+    label: contract.label,
+    description: contract.description,
+    promptSnippet: contract.promptSnippet,
+    parameters: contract.inputSchema,
+    async execute(toolCallId, params, signal) {
+      const client = requireClient(clientOption);
+      const resolutionProvider = requireResolutionProvider(resolutionProviderOption);
+      const type = params.entity_type ? resolveSearchType(params.entity_type) : void 0;
+      const resolution = await resolveEntities(resolutionProvider, [params.entity], type, signal, toolCallId);
+      if (resolution.issues.length > 0)
+        return needsInput("where_popular", resolution.issues, "Choose the intended Qloo entity.");
+      const entity = resolution.resolved[0];
+      if (!entity)
+        return needsInput("where_popular", [], "Provide an entity.");
+      const limit = params.limit ?? DEFAULT_LIMIT;
+      const query = {
+        "filter.type": "urn:heatmap",
+        "signal.interests.entities": entity.entityId,
+        "filter.location.query": params.within,
+        take: limit
+      };
+      const response = await client.insights(query, requestOptions(signal, toolCallId));
+      const results = [...resultArray(response, "heatmap")].sort((left, right) => heatmapAffinity(right) - heatmapAffinity(left)).slice(0, limit).map((point) => boundedValue(point));
+      return output("where_popular", {
+        status: results.length > 0 ? "ok" : "empty",
+        interpretation: { entity: interpretedEntity(entity), within: params.within },
+        ...resolutionOutput(resolutionProvider, resolution),
+        results,
+        result_count: results.length,
+        provenance: provenance("/v2/insights", "heatmaps-use-case", [query])
+      });
+    }
+  });
+}
+function makeCompareAudiencesTool(clientOption, resolutionProviderOption) {
+  const contract = QLOO_WORKFLOW_CONTRACTS.compare_audiences;
+  return defineTool({
+    name: contract.toolName,
+    label: contract.label,
+    description: contract.description,
+    promptSnippet: contract.promptSnippet,
+    parameters: contract.inputSchema,
+    async execute(toolCallId, params, signal) {
+      const client = requireClient(clientOption);
+      const resolutionProvider = requireResolutionProvider(resolutionProviderOption);
+      const [groupA, groupB] = await Promise.all([
+        resolveEntities(resolutionProvider, params.group_a, void 0, signal, toolCallId),
+        resolveEntities(resolutionProvider, params.group_b, void 0, signal, toolCallId)
+      ]);
+      const issues = [...groupA.issues, ...groupB.issues];
+      if (issues.length > 0)
+        return needsInput("compare_audiences", issues, "Choose or correct the unresolved comparison inputs.");
+      const query = {
+        "a.signal.interests.entities": groupA.resolved.map(({ entityId }) => entityId),
+        "b.signal.interests.entities": groupB.resolved.map(({ entityId }) => entityId),
+        take: params.limit ?? DEFAULT_LIMIT
+      };
+      if (params.target_type)
+        query["filter.type"] = resolveInsightsType(params.target_type);
+      const response = await client.compare(query, requestOptions(signal, toolCallId));
+      return output("compare_audiences", {
+        status: "ok",
+        interpretation: {
+          group_a: interpretedEntities(groupA.resolved),
+          group_b: interpretedEntities(groupB.resolved),
+          target_type: query["filter.type"]
+        },
+        ...resolutionOutput(resolutionProvider, groupA, groupB),
+        results: boundedValue(response.results),
+        provenance: provenance("/v2/analysis/compare", "analysis-compare", [query])
+      });
+    }
+  });
+}
+function makeEntityTagsTool(clientOption, resolutionProviderOption) {
+  const contract = QLOO_WORKFLOW_CONTRACTS.entity_tags;
+  return defineTool({
+    name: contract.toolName,
+    label: contract.label,
+    description: contract.description,
+    promptSnippet: contract.promptSnippet,
+    parameters: contract.inputSchema,
+    async execute(toolCallId, params, signal) {
+      const client = requireClient(clientOption);
+      const resolutionProvider = requireResolutionProvider(resolutionProviderOption);
+      const type = params.entity_type ? resolveSearchType(params.entity_type) : void 0;
+      const resolution = await resolveEntities(resolutionProvider, params.entities, type, signal, toolCallId);
+      if (resolution.issues.length > 0)
+        return needsInput("entity_tags", resolution.issues, "Choose or correct the unresolved Qloo entities.");
+      const query = {
+        "filter.type": "urn:tag",
+        "signal.interests.entities": resolution.resolved.map(({ entityId }) => entityId),
+        take: params.limit ?? DEFAULT_LIMIT
+      };
+      const response = await client.insights(query, requestOptions(signal, toolCallId));
+      const results = resultArray(response, "tags").map(compactTag).filter((tag) => tag !== void 0).slice(0, params.limit ?? DEFAULT_LIMIT);
+      return output("entity_tags", {
+        status: "ok",
+        interpretation: { entities: interpretedEntities(resolution.resolved) },
+        ...resolutionOutput(resolutionProvider, resolution),
+        results,
+        result_count: results.length,
+        provenance: provenance("/v2/insights", "taste-analysis", [query])
+      });
+    }
+  });
+}
+function makeAudienceDemographicsTool(clientOption, resolutionProviderOption) {
+  const contract = QLOO_WORKFLOW_CONTRACTS.audience_demographics;
+  return defineTool({
+    name: contract.toolName,
+    label: contract.label,
+    description: contract.description,
+    promptSnippet: contract.promptSnippet,
+    parameters: contract.inputSchema,
+    async execute(toolCallId, params, signal) {
+      const client = requireClient(clientOption);
+      const resolutionProvider = requireResolutionProvider(resolutionProviderOption);
+      const type = params.entity_type ? resolveSearchType(params.entity_type) : void 0;
+      const resolution = await resolveEntities(resolutionProvider, [params.entity], type, signal, toolCallId);
+      if (resolution.issues.length > 0)
+        return needsInput("audience_demographics", resolution.issues, "Choose the intended Qloo entity.");
+      const entity = resolution.resolved[0];
+      if (!entity)
+        return needsInput("audience_demographics", [], "Provide an entity.");
+      const query = {
+        "filter.type": "urn:demographics",
+        "signal.interests.entities": entity.entityId,
+        take: params.limit ?? DEFAULT_LIMIT
+      };
+      const response = await client.insights(query, requestOptions(signal, toolCallId));
+      const results = resultArray(response, "demographics").slice(0, params.limit ?? DEFAULT_LIMIT).map((item) => boundedValue(item));
+      return output("audience_demographics", {
+        status: "ok",
+        interpretation: { entity: interpretedEntity(entity) },
+        ...resolutionOutput(resolutionProvider, resolution),
+        results,
+        result_count: results.length,
+        provenance: provenance("/v2/insights", "demographics-use-case", [query])
+      });
+    }
+  });
+}
+function makeTrendsTool(clientOption, resolutionProviderOption) {
+  const contract = QLOO_WORKFLOW_CONTRACTS.trends;
+  return defineTool({
+    name: contract.toolName,
+    label: contract.label,
+    description: contract.description,
+    promptSnippet: contract.promptSnippet,
+    parameters: contract.inputSchema,
+    async execute(toolCallId, params, signal) {
+      const client = requireClient(clientOption);
+      const resolutionProvider = requireResolutionProvider(resolutionProviderOption);
+      if (!isCalendarDate(params.start_date) || !isCalendarDate(params.end_date) || params.start_date > params.end_date) {
+        throw new Error("Trend dates must be valid YYYY-MM-DD values with start_date on or before end_date.");
+      }
+      const type = resolveInsightsType(params.entity_type);
+      const resolution = await resolveEntities(resolutionProvider, params.entities, type, signal, toolCallId);
+      if (resolution.issues.length > 0)
+        return needsInput("trends", resolution.issues, "Choose or correct the unresolved Qloo entities.");
+      const requests = resolution.resolved.map((entity) => ({
+        entity,
+        query: {
+          "filter.type": type,
+          "filter.start_date": params.start_date,
+          "filter.end_date": params.end_date,
+          "signal.interests.entities": entity.entityId,
+          take: params.limit ?? DEFAULT_LIMIT
+        }
+      }));
+      const series = await Promise.all(requests.map(async ({ entity, query }) => {
+        const response = await client.trending(query, requestOptions(signal, toolCallId));
+        const points = resultArray(response, "trending").slice(0, params.limit ?? DEFAULT_LIMIT).map((point) => boundedValue(point));
+        return { entity: interpretedEntity(entity), points };
+      }));
+      return output("trends", {
+        status: "ok",
+        interpretation: { entity_type: type, start_date: params.start_date, end_date: params.end_date },
+        ...resolutionOutput(resolutionProvider, resolution),
+        series,
+        result_count: series.length,
+        provenance: provenance("/v2/trending", "get-trending", requests.map(({ query }) => query))
+      });
+    }
+  });
+}
+function makeFindTagsTool(clientOption) {
+  const contract = QLOO_WORKFLOW_CONTRACTS.find_tags;
+  return defineTool({
+    name: contract.toolName,
+    label: contract.label,
+    description: contract.description,
+    promptSnippet: contract.promptSnippet,
+    parameters: contract.inputSchema,
+    async execute(toolCallId, params, signal) {
+      const client = requireClient(clientOption);
+      const query = {
+        "filter.query": params.query,
+        "feature.semantic_search": params.semantic ?? true,
+        take: params.limit ?? DEFAULT_LIMIT
+      };
+      const response = await client.tags(query, requestOptions(signal, toolCallId));
+      const results = resultArray(response, "tags").map(compactTag).filter((tag) => tag !== void 0).slice(0, params.limit ?? DEFAULT_LIMIT);
+      return output("find_tags", {
+        status: "ok",
+        interpretation: { query: params.query, semantic: params.semantic ?? true },
+        results,
+        result_count: results.length,
+        provenance: provenance("/v2/tags", "get-tags", [query])
+      });
+    }
+  });
+}
+function createDirectOperationTools(client, resolutionProvider) {
+  return [
+    makeRecommendTool(client, resolutionProvider),
+    makeRankTool(client, resolutionProvider),
+    makeDescribeTool(client, resolutionProvider),
+    makeWherePopularTool(client, resolutionProvider),
+    makeCompareAudiencesTool(client, resolutionProvider),
+    makeEntityTagsTool(client, resolutionProvider),
+    makeAudienceDemographicsTool(client, resolutionProvider),
+    makeTrendsTool(client, resolutionProvider),
+    makeFindTagsTool(client)
+  ];
+}
+function createDirectQlooWorkflowExecutor(client, observer, resolutionProvider = createPublicQlooResolutionProvider(client)) {
+  const tools = new Map(createDirectOperationTools(client, resolutionProvider).map((tool) => [tool.name, tool]));
+  return createDelegatingQlooWorkflowExecutor({
+    transport: { kind: "direct", name: "Qloo API" },
+    resolution: resolutionProvider.descriptor,
+    ...observer ? { observer } : {},
+    async invoke(operation, input, context) {
+      const toolName = `qloo_${operation}`;
+      const tool = tools.get(toolName);
+      if (!tool)
+        throw new Error(`Direct Qloo executor does not implement ${toolName}.`);
+      const result = await tool.execute(context.correlationId ?? `direct-${operation}`, input, context.signal, void 0, {});
+      const details = result.details;
+      if (details === null || typeof details !== "object" || Array.isArray(details)) {
+        throw new Error(`${toolName} returned an invalid result envelope.`);
+      }
+      return details;
+    }
+  });
+}
+function makeExecutorTool(operation, executor) {
+  const contract = QLOO_WORKFLOW_CONTRACTS[operation];
+  const promptGuidelines = "promptGuidelines" in contract && Array.isArray(contract.promptGuidelines) ? contract.promptGuidelines : void 0;
+  return defineTool({
+    name: contract.toolName,
+    label: contract.label,
+    description: contract.description,
+    promptSnippet: contract.promptSnippet,
+    ...promptGuidelines ? { promptGuidelines: [...promptGuidelines] } : {},
+    parameters: contract.inputSchema,
+    renderShell: "self",
+    renderCall: (params, theme) => createQlooCallComponent(contract.toolName, params, theme),
+    renderResult: (result, renderOptions, theme) => createQlooResultComponent(result.details, renderOptions.expanded, theme),
+    async execute(toolCallId, params, signal) {
+      try {
+        const execution = await executor.execute(operation, params, {
+          ...signal ? { signal } : {},
+          correlationId: toolCallId
+        });
+        return {
+          content: [{ type: "text", text: JSON.stringify(execution.result) }],
+          details: execution.result
+        };
+      } catch (error) {
+        if (!(error instanceof QlooWorkflowExecutionError) || !error.expected)
+          throw error;
+        return output(operation, {
+          status: "error",
+          summary: error.message,
+          query_intent: createQlooQueryIntent(operation, params),
+          error: {
+            code: error.code,
+            layer: error.layer,
+            retryable: error.retryable,
+            recovery: error.recovery
+          },
+          results: [],
+          execution: {
+            transport: error.transport.kind,
+            transport_name: error.transport.name,
+            correlation_id: error.correlationId ?? toolCallId,
+            duration_ms: error.durationMs ?? 0
+          }
+        });
+      }
+    }
+  });
+}
+function createQlooTools(options = {}) {
+  if (options.client && options.executor) {
+    throw new Error("Choose either a Qloo client or a workflow executor, not both.");
+  }
+  if (options.executor && options.resolutionProvider) {
+    throw new Error("A custom workflow executor must own its resolution provider.");
+  }
+  const executor = options.executor ?? (options.client ? createDirectQlooWorkflowExecutor(options.client, options.executionObserver, options.resolutionProvider ?? createPublicQlooResolutionProvider(options.client)) : void 0);
+  if (!executor)
+    return associateRuntimeInfo([makeCapabilitiesTool()]);
+  return associateRuntimeInfo([
+    makeCapabilitiesTool(executor),
+    ...QLOO_WORKFLOW_OPERATION_IDS.map((operation) => makeExecutorTool(operation, executor))
+  ], executor);
+}
+function createDirectQlooWorkflowExecutorFromEnvironment(options = {}) {
+  const env = options.env ?? process.env;
+  const resolved = resolveQlooClientConfiguration({
+    env,
+    ...options.configPath ? { configPath: options.configPath } : {},
+    ...options.readConfigFile ? { readFile: options.readConfigFile } : {}
+  });
+  if (!resolved.apiKey)
+    return void 0;
+  const executionObserver = options.executionObserver ?? createFileExecutionObserver({
+    logsDirectory: resolveQlooPaths({ env }).logsDir
+  });
+  const client = new QlooClient({
+    apiKey: resolved.apiKey,
+    ...resolved.baseUrl ? { baseUrl: resolved.baseUrl } : {},
+    allowCustomBaseUrl: resolved.baseUrlTrusted
+  });
+  const resolutionProvider = options.resolutionProvider ?? createQlooResolutionProviderFromEnvironment({
+    client,
+    env,
+    fileConfig: resolved.fileConfig
+  });
+  return createDirectQlooWorkflowExecutor(client, executionObserver, resolutionProvider);
+}
+function createQlooToolsFromEnvironment(options = {}) {
+  if (options.executor) {
+    if (options.client)
+      throw new Error("Choose either a Qloo client or a workflow executor, not both.");
+    if (options.resolutionProvider)
+      throw new Error("A custom workflow executor must own its resolution provider.");
+    return createQlooTools({ executor: options.executor });
+  }
+  if (options.client) {
+    return createQlooTools({
+      client: options.client,
+      ...options.executionObserver ? { executionObserver: options.executionObserver } : {},
+      ...options.resolutionProvider ? { resolutionProvider: options.resolutionProvider } : {}
+    });
+  }
+  const executor = createDirectQlooWorkflowExecutorFromEnvironment(options);
+  return executor ? createQlooTools({ executor }) : createQlooTools();
+}
+export {
+  createDirectQlooWorkflowExecutor,
+  createDirectQlooWorkflowExecutorFromEnvironment,
+  createQlooTools,
+  createQlooToolsFromEnvironment,
+  getQlooToolRuntimeInfo
+};