@hraness/slopcamera 3.5.0 → 3.6.0

package/src/generation-pricing.ts

@@ -0,0 +1,217 @@
+/**
+ * Provider list prices for the image models Slopcamera can bill, and the
+ * cost of one Vercel AI Gateway image call derived from them.
+ *
+ * The AI Gateway charges the provider's list price with no markup
+ * (https://vercel.com/docs/ai-gateway/pricing, checked 2026-09-26), so the
+ * OpenAI and Recraft list prices below are what one call costs. Every price
+ * is integer micro-USD.
+ *
+ * A request never sets size or quality, so OpenAI chooses them ("auto"). The
+ * worst case is therefore the highest quality at the largest size, plus the
+ * prompt's text input tokens. Slopcamera never sends reference or edit
+ * images, so every input token is a text token.
+ */
+
+export type ProviderCostBasis = "reported" | "contractual" | "estimated" | "unknown"
+
+/** One provider cost line, in the shape Hraness Credits accepts. */
+export interface SlopcameraProviderCost {
+  readonly provider: string
+  readonly operation: string
+  readonly microUsd: number
+  readonly basis: ProviderCostBasis
+}
+
+/** Token counts a Gateway image call returned, as the AI SDK reports them. */
+export interface SlopcameraImageUsage {
+  readonly inputTokens?: number | undefined
+  readonly outputTokens?: number | undefined
+}
+
+interface TokenPricedImageModel {
+  readonly kind: "tokens"
+  /** Text input tokens, micro-USD per million. */
+  readonly textInputPerMillion: number
+  /**
+   * Output tokens, micro-USD per million. This is the image output rate,
+   * which is the highest output rate the model has, so it also bounds any
+   * text output tokens.
+   */
+  readonly outputPerMillion: number
+  /** OpenAI's published price for one high-quality 1024x1536 image. */
+  readonly worstImage: number
+  readonly source: string
+}
+
+interface ImagePricedModel {
+  readonly kind: "image"
+  /** Flat price for one image in the style Slopcamera requests (none). */
+  readonly perImage: number
+  readonly source: string
+}
+
+export type SlopcameraImageModelPrice = TokenPricedImageModel | ImagePricedModel
+
+export const slopcameraProviderPricesCheckedAt = "2026-09-26"
+
+/**
+ * Cited list prices. A model without an entry here cannot be billed: the
+ * hosted service refuses it before any hold.
+ */
+export const slopcameraImageModelPrices: Readonly<
+  Record<string, SlopcameraImageModelPrice>
+> = Object.freeze({
+  "openai/gpt-image-1": Object.freeze({
+    kind: "tokens",
+    textInputPerMillion: 5_000_000,
+    outputPerMillion: 40_000_000,
+    worstImage: 250_000,
+    source: "https://developers.openai.com/api/docs/models/gpt-image-1",
+  }),
+  "openai/gpt-image-1-mini": Object.freeze({
+    kind: "tokens",
+    textInputPerMillion: 2_000_000,
+    outputPerMillion: 8_000_000,
+    worstImage: 52_000,
+    source: "https://developers.openai.com/api/docs/models/gpt-image-1-mini",
+  }),
+  "openai/gpt-image-1.5": Object.freeze({
+    kind: "tokens",
+    textInputPerMillion: 5_000_000,
+    outputPerMillion: 32_000_000,
+    worstImage: 200_000,
+    source: "https://developers.openai.com/api/docs/models/gpt-image-1.5",
+  }),
+  "recraft/recraft-v4.1-utility": Object.freeze({
+    kind: "image",
+    perImage: 35_000,
+    source: "https://vercel.com/ai-gateway/models/recraft-v4.1-utility",
+  }),
+})
+
+/**
+ * Tokens allowed on top of the prompt's UTF-8 byte count when no usage came
+ * back. A byte-level BPE token covers at least one byte, so the byte count
+ * bounds the prompt's own tokens; the allowance covers request framing.
+ */
+export const slopcameraPromptTokenAllowance = 64
+
+export const slopcameraCostProvider = "vercel-ai-gateway"
+
+export function slopcameraImageModelPrice(
+  model: string,
+): SlopcameraImageModelPrice | undefined {
+  return Object.hasOwn(slopcameraImageModelPrices, model)
+    ? slopcameraImageModelPrices[model]
+    : undefined
+}
+
+function tokenCost(tokens: number, perMillion: number): number {
+  // Round up so a partial micro-dollar is never dropped.
+  return Math.ceil((tokens * perMillion) / 1_000_000)
+}
+
+function promptBytes(prompt: string): number {
+  return Buffer.byteLength(prompt, "utf8")
+}
+
+function validTokenCount(value: unknown): value is number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0
+}
+
+/**
+ * The most one image call for this model and prompt can cost: highest
+ * quality at the largest size, and every prompt byte counted as a token.
+ */
+export function worstCaseImageCostMicroUsd(
+  model: string,
+  prompt: string,
+): number | undefined {
+  const price = slopcameraImageModelPrice(model)
+  if (price === undefined) return undefined
+  if (price.kind === "image") return price.perImage
+  return (
+    price.worstImage +
+    tokenCost(
+      promptBytes(prompt) + slopcameraPromptTokenAllowance,
+      price.textInputPerMillion,
+    )
+  )
+}
+
+function estimatedLines(
+  model: string,
+  prompt: string,
+  price: SlopcameraImageModelPrice,
+): SlopcameraProviderCost[] {
+  if (price.kind === "image") {
+    return [{
+      provider: slopcameraCostProvider,
+      operation: `${model} image`,
+      microUsd: price.perImage,
+      basis: "estimated",
+    }]
+  }
+  return [
+    {
+      provider: slopcameraCostProvider,
+      operation: `${model} image output`,
+      microUsd: price.worstImage,
+      basis: "estimated",
+    },
+    {
+      provider: slopcameraCostProvider,
+      operation: `${model} text input`,
+      microUsd: tokenCost(
+        promptBytes(prompt) + slopcameraPromptTokenAllowance,
+        price.textInputPerMillion,
+      ),
+      basis: "estimated",
+    },
+  ]
+}
+
+/**
+ * Cost lines for one image call that reached the provider. Returned usage
+ * prices the call at the official per-token rates (basis "reported");
+ * without usage, the worst case stands in (basis "estimated").
+ */
+export function imageCallCosts(
+  model: string,
+  prompt: string,
+  usage: SlopcameraImageUsage | undefined,
+): SlopcameraProviderCost[] {
+  const price = slopcameraImageModelPrice(model)
+  if (price === undefined) {
+    return [{
+      provider: slopcameraCostProvider,
+      operation: `${model} image`,
+      microUsd: 0,
+      basis: "unknown",
+    }]
+  }
+  if (
+    price.kind === "tokens" &&
+    usage !== undefined &&
+    validTokenCount(usage.inputTokens) &&
+    validTokenCount(usage.outputTokens) &&
+    usage.outputTokens > 0
+  ) {
+    return [
+      {
+        provider: slopcameraCostProvider,
+        operation: `${model} image output`,
+        microUsd: tokenCost(usage.outputTokens, price.outputPerMillion),
+        basis: "reported",
+      },
+      {
+        provider: slopcameraCostProvider,
+        operation: `${model} text input`,
+        microUsd: tokenCost(usage.inputTokens, price.textInputPerMillion),
+        basis: "reported",
+      },
+    ]
+  }
+  return estimatedLines(model, prompt, price)
+}

package/src/support.ts

@@ -1,9 +1,15 @@
 import {
   maybeShowSupportInvitation,
   runSupportCommand,
+  supportAdvancedHelp,
+  supportHelpLine,
   type SupportCommandOptions,
 } from "@hraness/support-foundation/node"
 
+/** The one support line for root help, and the agent verbs for `help advanced`. */
+export const slopcameraSupportHelpLine = () => supportHelpLine({ command: ["slopcamera"] })
+export const slopcameraSupportAdvancedHelp = () => supportAdvancedHelp({ command: ["slopcamera"] })
+
 export const supportProfile = {
   id: "slopcamera",
   name: "Slopcamera",

package/src/version.ts

@@ -1 +1 @@
-export const SLOPCAMERA_VERSION = "3.5.0" as const
+export const SLOPCAMERA_VERSION = "3.6.0" as const

package/dist/index-77fjfg9f.js

@@ -1,3 +0,0 @@
-// @bun
-import{__require}from"./index-80a36bc0.js";import{createHash,randomUUID}from"crypto";import{link,rm,writeFile}from"fs/promises";import{dirname,extname,resolve}from"path";class SlopcameraCloudError extends Error{code;constructor(code,message,options){super(`[${code}] ${message}`,options);this.name="SlopcameraCloudError";this.code=code}}var slopcameraGatewayApiBaseUrl="https://ai-gateway.vercel.sh/v4/ai";var slopcameraImageModels=Object.freeze(["openai/gpt-image-1.5","recraft/recraft-v4.1-utility"]);var slopcameraResponseMediaTypes=Object.freeze(["image/png","image/jpeg","image/webp"]);var slopcameraMaximumPromptBytes=32*1024;var slopcameraMaximumRawImageBytes=64*1024*1024;var defaultGenerationTimeoutMs=5*60000;var maximumGenerationTimeoutMs=30*60000;var defaultMaximumGatewayResponseBytes=96*1024*1024;function invalidArgument(message){throw new SlopcameraCloudError("INVALID_ARGUMENT",message)}function credentialValue(value){if(value.length<16||value.length>16*1024||value.trim()!==value||/[^\x21-\x7e]/u.test(value)){throw new SlopcameraCloudError("AUTHENTICATION_REQUIRED","The selected Vercel AI Gateway credential is invalid.")}return value}function environment(injected){return injected??process.env}function resolveSlopcameraGatewayCredential(injected){const values=environment(injected);if(values.AI_GATEWAY_API_KEY!==undefined){return{source:"AI_GATEWAY_API_KEY",token:credentialValue(values.AI_GATEWAY_API_KEY)}}if(values.VERCEL_OIDC_TOKEN!==undefined){return{source:"VERCEL_OIDC_TOKEN",token:credentialValue(values.VERCEL_OIDC_TOKEN)}}throw new SlopcameraCloudError("AUTHENTICATION_REQUIRED","Set AI_GATEWAY_API_KEY or run Slopcamera through `vercel env run -- \u2026` with VERCEL_OIDC_TOKEN available.")}function slopcameraGatewayCredentialStatus(injected){const values=environment(injected);if(values.AI_GATEWAY_API_KEY!==undefined){credentialValue(values.AI_GATEWAY_API_KEY);return{available:true,source:"AI_GATEWAY_API_KEY"}}if(values.VERCEL_OIDC_TOKEN!==undefined){credentialValue(values.VERCEL_OIDC_TOKEN);return{available:true,source:"VERCEL_OIDC_TOKEN"}}return{available:false,source:null}}function validateModel(value){if(typeof value!=="string"||value.length<3||value.length>256||!/^[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._:-]*$/iu.test(value)){invalidArgument("Model must be a bounded Vercel AI Gateway provider/model id.")}return value}function validatePrompt(value){if(typeof value!=="string"||value.trim().length===0||/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/u.test(value)||Buffer.byteLength(value,"utf8")>slopcameraMaximumPromptBytes){invalidArgument(`Prompt must be non-empty and no more than ${slopcameraMaximumPromptBytes} UTF-8 bytes.`)}return value}function validateTimeout(value){const timeout=value??defaultGenerationTimeoutMs;if(!Number.isSafeInteger(timeout)||timeout<1000||timeout>maximumGenerationTimeoutMs){invalidArgument(`timeoutMs must be an integer from 1000 through ${maximumGenerationTimeoutMs}.`)}return timeout}function isObject(value){return typeof value==="object"&&value!==null||typeof value==="function"}function parseFunction(value){if(typeof value!=="function"){throw new SlopcameraCloudError("GENERATION_FAILED","The Vercel AI Gateway runtime is unavailable.")}return value}function disableAiSdkWarningLogging(){globalThis.AI_SDK_LOG_WARNINGS=false}function assertGenerationActive(signal){if(signal.aborted){throw new SlopcameraCloudError("GENERATION_FAILED","Vercel AI Gateway image generation was cancelled or exceeded its deadline.")}}async function loadDefaultGatewayRuntime(){let aiModule;let gatewayModule;try{[aiModule,gatewayModule]=await Promise.all([import("ai-v7"),import("@ai-sdk/gateway-v4")])}catch{throw new SlopcameraCloudError("GENERATION_FAILED","The Vercel AI Gateway runtime is unavailable.")}if(!isObject(aiModule)||!isObject(gatewayModule)){throw new SlopcameraCloudError("GENERATION_FAILED","The Vercel AI Gateway runtime is unavailable.")}const generateImage=parseFunction(aiModule.generateImage);if(typeof gatewayModule.createGateway!=="function"){throw new SlopcameraCloudError("GENERATION_FAILED","The Vercel AI Gateway runtime is unavailable.")}const createGateway=gatewayModule.createGateway;return{createGateway:(settings)=>{const provider=createGateway(settings);if(!isObject(provider)||typeof provider.imageModel!=="function"){throw new SlopcameraCloudError("GENERATION_FAILED","The Vercel AI Gateway runtime is unavailable.")}const imageModel=provider.imageModel;return{imageModel:(modelId)=>imageModel.call(provider,modelId)}},generateImage}}function gatewayUrl(input){try{if(input instanceof Request)return new URL(input.url);if(input instanceof URL)return new URL(input.href);return new URL(input,slopcameraGatewayApiBaseUrl)}catch{throw new SlopcameraCloudError("GENERATION_FAILED","The Vercel AI Gateway request was rejected.")}}function canonicalGatewayInput(input,url){if(!(input instanceof Request))return url;const snapshot=new Request(input);const body=snapshot.method==="GET"||snapshot.method==="HEAD"?undefined:snapshot.body??undefined;const requestInit={headers:snapshot.headers,method:snapshot.method,signal:snapshot.signal,...body===undefined?{}:{body,duplex:"half"}};return new Request(url.href,requestInit)}function boundedResponse(response,maximumBytes){const declared=response.headers.get("content-length");if(declared!==null){const value=Number(declared);if(!Number.isSafeInteger(value)||value<0||value>maximumBytes){response.body?.cancel().catch(()=>{return});throw new SlopcameraCloudError("GENERATION_INVALID_RESPONSE","Vercel AI Gateway returned an invalid bounded response.")}}if(response.body===null)return response;const reader=response.body.getReader();let bytes=0;const body=new ReadableStream({cancel:async(reason)=>await reader.cancel(reason),pull:async(controller)=>{try{const next=await reader.read();if(next.done){reader.releaseLock();controller.close();return}bytes+=next.value.byteLength;if(bytes>maximumBytes){await reader.cancel().catch(()=>{return});controller.error(new SlopcameraCloudError("GENERATION_INVALID_RESPONSE","Vercel AI Gateway returned an invalid bounded response."));return}controller.enqueue(next.value)}catch{controller.error(new SlopcameraCloudError("GENERATION_INVALID_RESPONSE","Vercel AI Gateway returned an invalid bounded response."))}}});return new Response(body,{headers:response.headers,status:response.status,statusText:response.statusText})}function createFixedGatewayFetch(options={}){const fetchImplementation=options.fetch??globalThis.fetch;const maximumResponseBytes=options.maximumResponseBytes??defaultMaximumGatewayResponseBytes;if(!Number.isSafeInteger(maximumResponseBytes)||maximumResponseBytes<1||maximumResponseBytes>1024*1024*1024){invalidArgument("maximumResponseBytes is outside the supported range.")}const fixed=new URL(slopcameraGatewayApiBaseUrl);return async(input,init)=>{const url=gatewayUrl(input);if(url.origin!==fixed.origin||url.pathname!==fixed.pathname&&!url.pathname.startsWith(`${fixed.pathname}/`)||url.username!==""||url.password!==""){throw new SlopcameraCloudError("GENERATION_FAILED","The Vercel AI Gateway request was rejected.")}const canonicalInput=canonicalGatewayInput(input,url);let response;try{response=await fetchImplementation(canonicalInput,{...init,redirect:"error"})}catch(error){if(error instanceof SlopcameraCloudError)throw error;throw new SlopcameraCloudError("GENERATION_FAILED","Vercel AI Gateway image generation failed; the request was not retried.")}if(response.redirected||response.status>=300&&response.status<400){await response.body?.cancel().catch(()=>{return});throw new SlopcameraCloudError("GENERATION_FAILED","The Vercel AI Gateway request was rejected.")}return boundedResponse(response,maximumResponseBytes)}}function combineSignals(caller,timeoutMs){const controller=new AbortController;const abort=()=>controller.abort(caller?.reason);let rejectInterruption;const interruption=new Promise((_resolve,reject)=>{rejectInterruption=reject});const rejectOnAbort=()=>{rejectInterruption?.(new SlopcameraCloudError("GENERATION_FAILED","Vercel AI Gateway image generation was cancelled or exceeded its deadline."))};controller.signal.addEventListener("abort",rejectOnAbort,{once:true});if(caller?.aborted===true)abort();caller?.addEventListener("abort",abort,{once:true});const timer=setTimeout(()=>controller.abort(),timeoutMs);return{dispose:()=>{clearTimeout(timer);caller?.removeEventListener("abort",abort);controller.signal.removeEventListener("abort",rejectOnAbort);rejectInterruption=undefined},interruption,signal:controller.signal}}function mediaType(value){if(typeof value!=="string"||!slopcameraResponseMediaTypes.includes(value)){throw new SlopcameraCloudError("GENERATION_INVALID_RESPONSE","Vercel AI Gateway returned an unsupported image type.")}return value}function validImageBytes(bytes,type){if(bytes.byteLength<12||bytes.byteLength>slopcameraMaximumRawImageBytes){return false}if(type==="image/png"){return Buffer.from(bytes.subarray(0,8)).equals(Buffer.from([137,80,78,71,13,10,26,10]))}if(type==="image/jpeg"){return bytes[0]===255&&bytes[1]===216&&bytes.at(-2)===255&&bytes.at(-1)===217}return bytes.byteLength>=16&&Buffer.from(bytes.subarray(0,4)).toString("ascii")==="RIFF"&&Buffer.from(bytes).readUInt32LE(4)===bytes.byteLength-8&&Buffer.from(bytes.subarray(8,12)).toString("ascii")==="WEBP"&&["VP8 ","VP8L","VP8X"].includes(Buffer.from(bytes.subarray(12,16)).toString("ascii"))}function warningReceipt(value){let type="provider-warning";let detail="Provider warning";if(typeof value==="string"){detail=value}else if(isObject(value)){if(typeof value.type==="string"&&value.type.length<=64){type=value.type.replace(/[^a-z0-9._-]/giu,"-")||type}if(typeof value.message==="string")detail=value.message;else if(typeof value.details==="string")detail=value.details}return`${type} sha256:${createHash("sha256").update(detail).digest("hex")}`}function parseResult(value,model){if(!isObject(value)||!Array.isArray(value.images)||value.images.length!==1){throw new SlopcameraCloudError("GENERATION_INVALID_RESPONSE","Vercel AI Gateway did not return exactly one image.")}const image=value.images[0];if(!isObject(image)||!(image.uint8Array instanceof Uint8Array)){throw new SlopcameraCloudError("GENERATION_INVALID_RESPONSE","Vercel AI Gateway returned an invalid bounded image.")}const type=mediaType(image.mediaType);if(!validImageBytes(image.uint8Array,type)){throw new SlopcameraCloudError("GENERATION_INVALID_RESPONSE","Vercel AI Gateway returned an invalid bounded image.")}const gateway=isObject(value.providerMetadata)&&isObject(value.providerMetadata.gateway)?value.providerMetadata.gateway:undefined;const foreignGenerationId=gateway!==undefined&&typeof gateway.generationId==="string"&&gateway.generationId.length>0&&gateway.generationId.length<=256&&!/[\u0000-\u001f\u007f]/u.test(gateway.generationId)?gateway.generationId:randomUUID();const requestId=`sha256:${createHash("sha256").update("slopcamera.gateway-generation-id/v1\x00").update(foreignGenerationId).digest("hex")}`;const warnings=Array.isArray(value.warnings)?value.warnings.slice(0,100).map(warningReceipt):[];return{bytes:image.uint8Array,response:{image:{base64:Buffer.from(image.uint8Array).toString("base64"),mediaType:type},model,provider:"vercel-ai-gateway",requestId,warnings}}}async function performGeneration(input,dependencies){const model=validateModel(input.model);const prompt=validatePrompt(input.prompt);const credential=resolveSlopcameraGatewayCredential(dependencies.environment);const timeout=combineSignals(input.signal,validateTimeout(input.timeoutMs));try{const generation=(async()=>{assertGenerationActive(timeout.signal);disableAiSdkWarningLogging();const runtime=await(dependencies.loadRuntime??loadDefaultGatewayRuntime)();assertGenerationActive(timeout.signal);const provider=runtime.createGateway({apiKey:credential.token,baseURL:slopcameraGatewayApiBaseUrl,fetch:createFixedGatewayFetch({...dependencies.fetch===undefined?{}:{fetch:dependencies.fetch},...dependencies.maximumResponseBytes===undefined?{}:{maximumResponseBytes:dependencies.maximumResponseBytes}})});assertGenerationActive(timeout.signal);const generated=await runtime.generateImage({abortSignal:timeout.signal,maxRetries:0,model:provider.imageModel(model),n:1,prompt});return parseResult(generated,model)})();return await Promise.race([generation,timeout.interruption])}catch(error){if(error instanceof SlopcameraCloudError)throw error;throw new SlopcameraCloudError("GENERATION_FAILED","Vercel AI Gateway image generation failed; the request was not retried.")}finally{timeout.dispose()}}async function generateSlopcameraImage(input,dependencies={}){return(await performGeneration(input,dependencies)).response}function expectedMediaType(outputPath){const extension=extname(outputPath).toLocaleLowerCase("en-US");if(extension===".png")return"image/png";if(extension===".jpg"||extension===".jpeg")return"image/jpeg";if(extension===".webp")return"image/webp";invalidArgument("Output path must end in .png, .jpg, .jpeg, or .webp.")}async function atomicImageWrite(outputPath,bytes){const absolutePath=resolve(outputPath);const temporaryPath=resolve(dirname(absolutePath),`.${randomUUID()}.slopcamera-generate.tmp`);try{await writeFile(temporaryPath,bytes,{flag:"wx"});await link(temporaryPath,absolutePath);return absolutePath}catch{throw new SlopcameraCloudError("OUTPUT_WRITE_FAILED","Slopcamera could not atomically write the generated image.")}finally{await rm(temporaryPath,{force:true}).catch(()=>{return})}}async function generateSlopcameraImageFile(input,dependencies={}){if(typeof input.outputPath!=="string"||input.outputPath.length<1||input.outputPath.length>4096||input.outputPath.includes("\x00")){invalidArgument("Output path must be a non-empty local path.")}const expected=expectedMediaType(input.outputPath);const generated=await performGeneration(input,dependencies);if(generated.response.image.mediaType!==expected){throw new SlopcameraCloudError("GENERATION_INVALID_RESPONSE",`Generated ${generated.response.image.mediaType} does not match the requested ${expected} output path.`)}const outputPath=await atomicImageWrite(input.outputPath,generated.bytes);return{bytes:generated.bytes.byteLength,mediaType:generated.response.image.mediaType,model:generated.response.model,outputPath,provider:generated.response.provider,requestId:generated.response.requestId,sha256:createHash("sha256").update(generated.bytes).digest("hex"),warnings:generated.response.warnings}}
-export{SlopcameraCloudError,slopcameraGatewayApiBaseUrl,slopcameraImageModels,slopcameraResponseMediaTypes,slopcameraMaximumPromptBytes,slopcameraMaximumRawImageBytes,resolveSlopcameraGatewayCredential,slopcameraGatewayCredentialStatus,createFixedGatewayFetch,generateSlopcameraImage,generateSlopcameraImageFile};