promptopskit 0.2.5 → 0.3.0

package/dist/index.cjs

@@ -35,7 +35,15 @@ __export(src_exports, {
   PromptOpsKit: () => PromptOpsKit,
   anthropicAdapter: () => anthropicAdapter,
   applyOverrides: () => applyOverrides,
+  applyUsageTapEntitlements: () => applyUsageTapEntitlements,
+  beginUsageTapCall: () => beginUsageTapCall,
   createPromptOpsKit: () => createPromptOpsKit,
+  createUsageTapClient: () => createUsageTapClient,
+  defaultUsageTapErrorMapper: () => defaultUsageTapErrorMapper,
+  endUsageTapCall: () => endUsageTapCall,
+  extractAnthropicUsage: () => extractAnthropicUsage,
+  extractGeminiUsage: () => extractGeminiUsage,
+  extractOpenAIUsage: () => extractOpenAIUsage,
   extractSections: () => extractSections,
   extractVariables: () => extractVariables,
   geminiAdapter: () => geminiAdapter,
@@ -47,8 +55,13 @@ __export(src_exports, {
   parsePrompt: () => parsePrompt,
   renderPrompt: () => renderPrompt,
   resolveIncludes: () => resolveIncludes,
+  runAnthropicWithUsageTap: () => runAnthropicWithUsageTap,
+  runGeminiWithUsageTap: () => runGeminiWithUsageTap,
+  runOpenAIWithUsageTap: () => runOpenAIWithUsageTap,
+  runOpenRouterWithUsageTap: () => runOpenRouterWithUsageTap,
   validateAsset: () => validateAsset,
-  validateAssetWithIncludes: () => validateAssetWithIncludes
+  validateAssetWithIncludes: () => validateAssetWithIncludes,
+  withUsageTapCall: () => withUsageTapCall
 });
 module.exports = __toCommonJS(src_exports);
 var import_promises3 = require("fs/promises");
@@ -92,8 +105,16 @@ var ResponseSchema = import_zod.z.object({
 var HistorySchema = import_zod.z.object({
   max_items: import_zod.z.number().int().positive().optional()
 });
+var ContextInputDefinitionObjectSchema = import_zod.z.object({
+  name: import_zod.z.string(),
+  max_size: import_zod.z.number().int().positive().optional()
+});
+var ContextInputDefinitionSchema = import_zod.z.union([
+  import_zod.z.string(),
+  ContextInputDefinitionObjectSchema
+]);
 var ContextSchema = import_zod.z.object({
-  inputs: import_zod.z.array(import_zod.z.string()).optional(),
+  inputs: import_zod.z.array(ContextInputDefinitionSchema).optional(),
   history: HistorySchema.optional()
 });
 var MetadataSchema = import_zod.z.object({
@@ -694,6 +715,48 @@ function getAdapter(provider) {
   return adapter;
 }
 
+// src/context.ts
+var textEncoder = new TextEncoder();
+function getContextInputs(asset) {
+  return (asset.context?.inputs ?? []).map(normalizeContextInput);
+}
+function getContextInputNames(asset) {
+  return getContextInputs(asset).map((input) => input.name);
+}
+function normalizeContextInput(input) {
+  if (typeof input === "string") {
+    return { name: input };
+  }
+  return {
+    name: input.name,
+    max_size: input.max_size
+  };
+}
+function measureContextValueSize(value) {
+  return textEncoder.encode(value).length;
+}
+function collectContextSizeWarnings(asset, variables = {}) {
+  const warnings = [];
+  for (const input of getContextInputs(asset)) {
+    if (input.max_size === void 0) {
+      continue;
+    }
+    const value = variables[input.name];
+    if (value === void 0) {
+      continue;
+    }
+    const actualSize = measureContextValueSize(value);
+    if (actualSize > input.max_size) {
+      warnings.push({
+        variable: input.name,
+        maxSize: input.max_size,
+        actualSize
+      });
+    }
+  }
+  return warnings;
+}
+
 // src/validation/levenshtein.ts
 function levenshtein(a, b) {
   const m = a.length;
@@ -775,7 +838,7 @@ function validateAsset(asset, frontMatterKeys, filePath) {
       }
     }
   }
-  const declaredInputs = new Set(asset.context?.inputs ?? []);
+  const declaredInputs = new Set(getContextInputNames(asset));
   const usedVars = /* @__PURE__ */ new Set();
   if (asset.sections?.system_instructions) {
     for (const v of extractVariables(asset.sections.system_instructions)) {
@@ -884,7 +947,398 @@ var PromptCache = class {
   }
 };
 
+// src/usagetap/client.ts
+var DEFAULT_BASE_URL = "https://api.usagetap.com";
+var ACCEPT_HEADER = "application/vnd.usagetap.v1+json";
+function createUsageTapHttpError(status, body) {
+  const error = new Error(`UsageTap request failed with status ${status}`);
+  error.statusCode = status;
+  error.body = body;
+  return error;
+}
+function createUsageTapClient(config) {
+  const fetchImpl = config.fetch ?? globalThis.fetch;
+  if (!fetchImpl) {
+    throw new Error("Fetch API is not available. Provide config.fetch when creating the UsageTap client.");
+  }
+  const baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+  async function request(path, body, init = {}) {
+    const response = await fetchImpl(`${baseUrl}${path}`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${config.apiKey}`,
+        Accept: ACCEPT_HEADER,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(body),
+      signal: init.signal
+    });
+    const text = await response.text();
+    const parsed = text ? JSON.parse(text) : {};
+    if (!response.ok) {
+      throw createUsageTapHttpError(response.status, parsed);
+    }
+    return parsed;
+  }
+  return {
+    request,
+    beginCall(begin, init) {
+      return request("/call_begin", begin, init);
+    },
+    endCall(end, init) {
+      return request("/call_end", end, init);
+    }
+  };
+}
+
+// src/usagetap/lifecycle.ts
+function isObject(value) {
+  return typeof value === "object" && value !== null;
+}
+function isInvokeResult(value) {
+  return isObject(value) && "result" in value && "usage" in value;
+}
+function getErrorStatusCode(error) {
+  if (!isObject(error)) {
+    return void 0;
+  }
+  if (typeof error.statusCode === "number") {
+    return error.statusCode;
+  }
+  if (typeof error.status === "number") {
+    return error.status;
+  }
+  if (isObject(error.response) && typeof error.response.status === "number") {
+    return error.response.status;
+  }
+  return void 0;
+}
+function attachEndErrorCause(thrownError, endError) {
+  if (thrownError instanceof Error) {
+    if (thrownError.cause === void 0) {
+      Object.defineProperty(thrownError, "cause", {
+        value: endError,
+        configurable: true,
+        writable: true
+      });
+    }
+    throw thrownError;
+  }
+  throw new AggregateError([thrownError, endError], "Vendor call failed and UsageTap call_end also failed.");
+}
+function defaultUsageTapErrorMapper(error) {
+  return {
+    code: "VENDOR_ERROR",
+    message: String(error)
+  };
+}
+function beginUsageTapCall(client, begin, init) {
+  return client.beginCall(begin, init);
+}
+function endUsageTapCall(client, end, init) {
+  return client.endCall(end, init);
+}
+async function withUsageTapCall(client, options) {
+  const begin = await beginUsageTapCall(client, options.begin, { signal: options.signal });
+  const onError = options.onError ?? defaultUsageTapErrorMapper;
+  let result;
+  let usage;
+  let thrownError;
+  const setUsage = (nextUsage) => {
+    usage = { ...usage, ...nextUsage };
+  };
+  try {
+    const invoked = await options.invoke({
+      begin,
+      setUsage,
+      signal: options.signal
+    });
+    if (isInvokeResult(invoked)) {
+      result = invoked.result;
+      setUsage(invoked.usage);
+    } else {
+      result = invoked;
+    }
+  } catch (error) {
+    thrownError = error;
+  }
+  const effectiveUsage = {
+    ...usage
+  };
+  if (thrownError) {
+    effectiveUsage.error = effectiveUsage.error ?? onError(thrownError);
+    effectiveUsage.responseStatusCode = effectiveUsage.responseStatusCode ?? getErrorStatusCode(thrownError);
+  } else {
+    effectiveUsage.responseStatusCode = effectiveUsage.responseStatusCode ?? 200;
+  }
+  let end;
+  try {
+    end = await endUsageTapCall(client, {
+      callId: begin.data.callId,
+      ...effectiveUsage
+    }, { signal: options.signal });
+  } catch (endError) {
+    if (thrownError) {
+      attachEndErrorCause(thrownError, endError);
+    }
+    throw endError;
+  }
+  if (thrownError) {
+    throw thrownError;
+  }
+  return {
+    result,
+    begin,
+    end,
+    effectiveUsage
+  };
+}
+
+// src/usagetap/providers.ts
+function cloneRequest(request) {
+  return structuredClone(request);
+}
+function isObject2(value) {
+  return typeof value === "object" && value !== null;
+}
+function isRecordArray(value) {
+  return Array.isArray(value) && value.every((item) => isObject2(item));
+}
+function isInvokeResult2(value) {
+  return isObject2(value) && "result" in value && "usage" in value;
+}
+function capabilityAllowed(allowed, capability) {
+  return allowed[capability] !== false;
+}
+function reasoningLevelOrder(level) {
+  switch (level) {
+    case "HIGH":
+      return 3;
+    case "MEDIUM":
+      return 2;
+    case "LOW":
+      return 1;
+    default:
+      return 0;
+  }
+}
+function capOpenAIReasoning(body, allowed) {
+  if (typeof body.reasoning_effort !== "string") {
+    return;
+  }
+  const current = String(body.reasoning_effort).toUpperCase();
+  const allowedLevel = allowed.reasoningLevel ?? "HIGH";
+  if (allowedLevel === "NONE") {
+    delete body.reasoning_effort;
+    return;
+  }
+  if (reasoningLevelOrder(current) > reasoningLevelOrder(allowedLevel)) {
+    body.reasoning_effort = allowedLevel.toLowerCase();
+  }
+}
+function capGeminiReasoning(body, allowed) {
+  if (allowed.reasoningLevel === "NONE") {
+    delete body.thinkingConfig;
+    return;
+  }
+  const budgets = {
+    LOW: 1024,
+    MEDIUM: 4096,
+    HIGH: 8192
+  };
+  const allowedBudget = allowed.reasoningLevel ? budgets[allowed.reasoningLevel] : void 0;
+  if (allowedBudget === void 0) {
+    return;
+  }
+  if (!isObject2(body.thinkingConfig)) {
+    body.thinkingConfig = { thinkingBudget: allowedBudget };
+    return;
+  }
+  const thinkingConfig = body.thinkingConfig;
+  if (typeof thinkingConfig.thinkingBudget === "number") {
+    thinkingConfig.thinkingBudget = Math.min(thinkingConfig.thinkingBudget, allowedBudget);
+    return;
+  }
+  thinkingConfig.thinkingBudget = allowedBudget;
+}
+function applyModelTier(request, allowed, options) {
+  const nextModel = allowed.premium && options.modelTiers?.premium ? options.modelTiers.premium : allowed.standard && options.modelTiers?.standard ? options.modelTiers.standard : void 0;
+  if (!nextModel) {
+    return;
+  }
+  request.model = nextModel;
+  if (isObject2(request.body) && "model" in request.body) {
+    request.body.model = nextModel;
+  }
+}
+function filterOpenAITools(tools, allowed, options) {
+  return tools.filter((tool) => {
+    if (tool.type === "web_search" && allowed.search === false) {
+      return false;
+    }
+    const functionDef = isObject2(tool.function) ? tool.function : void 0;
+    const name = typeof functionDef?.name === "string" ? functionDef.name : typeof tool.name === "string" ? tool.name : typeof tool.type === "string" ? tool.type : void 0;
+    if (!name) {
+      return true;
+    }
+    const capability = options.toolEntitlements?.[name];
+    return capability ? capabilityAllowed(allowed, capability) : true;
+  });
+}
+function filterAnthropicTools(tools, allowed, options) {
+  return tools.filter((tool) => {
+    const name = typeof tool.name === "string" ? tool.name : void 0;
+    if (!name) {
+      return true;
+    }
+    const capability = options.toolEntitlements?.[name];
+    return capability ? capabilityAllowed(allowed, capability) : true;
+  });
+}
+function filterGeminiTools(tools, allowed, options) {
+  return tools.map((tool) => {
+    const declarations = Array.isArray(tool.functionDeclarations) ? tool.functionDeclarations.filter((declaration) => {
+      if (!isObject2(declaration) || typeof declaration.name !== "string") {
+        return true;
+      }
+      const capability = options.toolEntitlements?.[declaration.name];
+      return capability ? capabilityAllowed(allowed, capability) : true;
+    }) : tool.functionDeclarations;
+    return {
+      ...tool,
+      functionDeclarations: declarations
+    };
+  }).filter((tool) => {
+    if (!Array.isArray(tool.functionDeclarations)) {
+      return true;
+    }
+    return tool.functionDeclarations.length > 0;
+  });
+}
+function applyUsageTapEntitlements(request, begin, options = {}) {
+  const nextRequest = cloneRequest(request);
+  const allowed = begin.data.allowed ?? {};
+  applyModelTier(nextRequest, allowed, options);
+  if (!isObject2(nextRequest.body)) {
+    return nextRequest;
+  }
+  if (nextRequest.provider === "openai" || nextRequest.provider === "openrouter") {
+    capOpenAIReasoning(nextRequest.body, allowed);
+    if (isRecordArray(nextRequest.body.tools)) {
+      nextRequest.body.tools = filterOpenAITools(nextRequest.body.tools, allowed, options);
+    }
+    return nextRequest;
+  }
+  if (nextRequest.provider === "gemini") {
+    capGeminiReasoning(nextRequest.body, allowed);
+    if (isRecordArray(nextRequest.body.tools)) {
+      nextRequest.body.tools = filterGeminiTools(nextRequest.body.tools, allowed, options);
+    }
+    return nextRequest;
+  }
+  if (nextRequest.provider === "anthropic" && isRecordArray(nextRequest.body.tools)) {
+    nextRequest.body.tools = filterAnthropicTools(nextRequest.body.tools, allowed, options);
+  }
+  return nextRequest;
+}
+function extractOpenAIUsage(response, meta = {}) {
+  const usage = isObject2(response) && isObject2(response.usage) ? response.usage : {};
+  const promptDetails = isObject2(usage.prompt_tokens_details) ? usage.prompt_tokens_details : {};
+  const completionDetails = isObject2(usage.completion_tokens_details) ? usage.completion_tokens_details : {};
+  return {
+    modelUsed: meta.modelUsed,
+    inputTokens: typeof usage.prompt_tokens === "number" ? usage.prompt_tokens : 0,
+    responseTokens: typeof usage.completion_tokens === "number" ? usage.completion_tokens : 0,
+    cachedInputTokens: typeof promptDetails.cached_tokens === "number" ? promptDetails.cached_tokens : void 0,
+    reasoningTokens: typeof completionDetails.reasoning_tokens === "number" ? completionDetails.reasoning_tokens : void 0,
+    responseStatusCode: meta.responseStatusCode ?? 200
+  };
+}
+function extractAnthropicUsage(response, meta = {}) {
+  const usage = isObject2(response) && isObject2(response.usage) ? response.usage : {};
+  return {
+    modelUsed: meta.modelUsed,
+    inputTokens: typeof usage.input_tokens === "number" ? usage.input_tokens : 0,
+    responseTokens: typeof usage.output_tokens === "number" ? usage.output_tokens : 0,
+    cachedInputTokens: typeof usage.cache_read_input_tokens === "number" ? usage.cache_read_input_tokens : void 0,
+    responseStatusCode: meta.responseStatusCode ?? 200
+  };
+}
+function extractGeminiUsage(response, meta = {}) {
+  const usage = isObject2(response) && isObject2(response.usageMetadata) ? response.usageMetadata : {};
+  return {
+    modelUsed: meta.modelUsed,
+    inputTokens: typeof usage.promptTokenCount === "number" ? usage.promptTokenCount : 0,
+    responseTokens: typeof usage.candidatesTokenCount === "number" ? usage.candidatesTokenCount : 0,
+    cachedInputTokens: typeof usage.cachedContentTokenCount === "number" ? usage.cachedContentTokenCount : void 0,
+    reasoningTokens: typeof usage.thoughtsTokenCount === "number" ? usage.thoughtsTokenCount : void 0,
+    responseStatusCode: meta.responseStatusCode ?? 200
+  };
+}
+async function runProviderWithUsageTap(client, options, defaultExtractor) {
+  let requestUsed = cloneRequest(options.request);
+  const lifecycle = await withUsageTapCall(client, {
+    begin: options.begin,
+    signal: options.signal,
+    onError: options.onError ?? defaultUsageTapErrorMapper,
+    invoke: async ({ begin, setUsage }) => {
+      requestUsed = options.entitlementMode === "apply" ? applyUsageTapEntitlements(options.request, begin, options) : cloneRequest(options.request);
+      const invoked = await options.invoke(requestUsed);
+      if (isInvokeResult2(invoked)) {
+        return invoked;
+      }
+      const response = invoked;
+      const usage = (options.extractUsage ?? defaultExtractor)(response, {
+        modelUsed: requestUsed.model,
+        responseStatusCode: 200
+      });
+      setUsage(usage);
+      return response;
+    }
+  });
+  return {
+    response: lifecycle.result,
+    begin: lifecycle.begin,
+    end: lifecycle.end,
+    requestUsed,
+    effectiveUsage: lifecycle.effectiveUsage,
+    allowed: lifecycle.begin.data.allowed ?? {}
+  };
+}
+function runOpenAIWithUsageTap(client, options) {
+  return runProviderWithUsageTap(client, options, extractOpenAIUsage);
+}
+function runOpenRouterWithUsageTap(client, options) {
+  return runProviderWithUsageTap(client, options, extractOpenAIUsage);
+}
+function runAnthropicWithUsageTap(client, options) {
+  return runProviderWithUsageTap(client, options, extractAnthropicUsage);
+}
+function runGeminiWithUsageTap(client, options) {
+  return runProviderWithUsageTap(client, options, extractGeminiUsage);
+}
+
 // src/index.ts
+function shouldIncludeContextWarningsInResult(policy) {
+  return policy === void 0 || policy === "auto" || policy === "result-only" || policy === "console-and-result";
+}
+function shouldLogContextWarnings(policy, options, mode) {
+  if (policy === "off" || policy === "result-only") {
+    return false;
+  }
+  if (policy === "console" || policy === "console-and-result") {
+    return true;
+  }
+  return Boolean(options.source || mode !== "compiled-only");
+}
+function formatContextSizeWarning(asset, warning) {
+  return [
+    "POK030:",
+    `Context variable "${warning.variable}" exceeded max_size`,
+    `for prompt "${asset.id}"`,
+    `(${warning.actualSize} bytes > ${warning.maxSize} bytes).`
+  ].join(" ");
+}
 var PromptOpsKit = class {
   config;
   promptCache;
@@ -995,6 +1449,15 @@ ${paths.map((p) => `  - ${p}`).join("\n")}`
 ` + validation.errors.map((e) => `  - ${e}`).join("\n")
       );
     }
+    const contextSizeWarnings = collectContextSizeWarnings(resolved, options.variables).map(
+      (warning) => formatContextSizeWarning(resolved, warning)
+    );
+    const contextWarningPolicy = this.config.warnings?.contextSize;
+    if (contextSizeWarnings.length > 0 && shouldLogContextWarnings(contextWarningPolicy, options, this.config.mode)) {
+      for (const warning of contextSizeWarnings) {
+        console.warn(`[promptopskit] Warning: ${warning}`);
+      }
+    }
     const request = adapter.render(resolved, {
       variables: options.variables,
       history: options.history,
@@ -1004,7 +1467,7 @@ ${paths.map((p) => `  - ${p}`).join("\n")}`
     return {
       resolved,
       request,
-      warnings: validation.warnings
+      warnings: shouldIncludeContextWarningsInResult(contextWarningPolicy) ? [...validation.warnings, ...contextSizeWarnings] : validation.warnings
     };
   }
   /**
@@ -1027,7 +1490,8 @@ function createPromptOpsKit(config) {
 async function renderPrompt(options) {
   const kit = createPromptOpsKit({
     sourceDir: options.sourceDir ?? ".",
-    cache: false
+    cache: false,
+    warnings: options.warnings
   });
   return kit.renderPrompt(options);
 }
@@ -1038,7 +1502,15 @@ async function renderPrompt(options) {
   PromptOpsKit,
   anthropicAdapter,
   applyOverrides,
+  applyUsageTapEntitlements,
+  beginUsageTapCall,
   createPromptOpsKit,
+  createUsageTapClient,
+  defaultUsageTapErrorMapper,
+  endUsageTapCall,
+  extractAnthropicUsage,
+  extractGeminiUsage,
+  extractOpenAIUsage,
   extractSections,
   extractVariables,
   geminiAdapter,
@@ -1050,7 +1522,12 @@ async function renderPrompt(options) {
   parsePrompt,
   renderPrompt,
   resolveIncludes,
+  runAnthropicWithUsageTap,
+  runGeminiWithUsageTap,
+  runOpenAIWithUsageTap,
+  runOpenRouterWithUsageTap,
   validateAsset,
-  validateAssetWithIncludes
+  validateAssetWithIncludes,
+  withUsageTapCall
 });
 //# sourceMappingURL=index.cjs.map