humanish 0.17.0 → 0.19.0

package/dist/pricing.d.ts

@@ -0,0 +1,78 @@
+import type { ActorTokenUsage } from "./actor-contract.js";
+export declare const PRICING_SCHEMA = "humanish.pricing.v1";
+export declare const ACTOR_ESTIMATED_COST_SCHEMA = "humanish.actor-estimated-cost.v1";
+export interface ModelRate {
+    /** USD per input token (the per-1M equivalent is noted in the comment beside each entry). */
+    inputUsdPerToken: number;
+    /** USD per output token. */
+    outputUsdPerToken: number;
+    /** "YYYY-MM-DD" the entry was last checked against `source`. */
+    asOf: string;
+    /** Public pricing page the number came from (a comment/URL, never a secret). */
+    source: string;
+    /** true = a stand-in NOT copied from a live sheet; the estimate carries this flag so a
+     *  placeholder rate is never mistaken for a confirmed one. */
+    placeholder?: boolean;
+}
+export interface DesktopRate {
+    usdPerMinute: number;
+    asOf: string;
+    source: string;
+    placeholder?: boolean;
+}
+/**
+ * The token-derived cost ESTIMATE for one actor lane. `estimatedCostUsd: null` = DECLARED ABSENT
+ * (unknown rate or no token usage) — never coerced to 0. A non-null figure ALWAYS carries its
+ * pricing provenance (`ratesAsOf` + `source`) so the mechanism (a rate-table multiply) matches
+ * the claim (an estimate, not a charge). Defined here so the rate table and the field that
+ * consumes it live together; `ActorTrace` imports it type-only.
+ */
+export interface ActorEstimatedCost {
+    schema: typeof ACTOR_ESTIMATED_COST_SCHEMA;
+    /** null = declared absent (no rate for the model / no token usage). */
+    estimatedCostUsd: number | null;
+    reason?: "no_rate_for_model" | "no_token_usage";
+    /** Pricing provenance date; null iff estimatedCostUsd is null. */
+    ratesAsOf: string | null;
+    /** The pricing-page URL/comment that produced the rate. */
+    source?: string;
+    /** The model id the estimate was keyed on. */
+    modelId?: string;
+    /** true when the rate is a stand-in, not a live sheet. */
+    placeholder?: boolean;
+    breakdown?: {
+        inputUsd: number;
+        outputUsd: number;
+        inputTokens: number;
+        outputTokens: number;
+    };
+}
+/** The desktop-minute cost ESTIMATE (host-side create->teardown span * a per-minute rate). Same
+ *  null-discipline as ActorEstimatedCost: `estimatedCostUsd: null` = not measured (no duration). */
+export interface DesktopCostEstimate {
+    estimatedCostUsd: number | null;
+    reason?: "no_duration";
+    ratesAsOf: string | null;
+    source?: string;
+    /** The billed minutes the estimate was keyed on; null when no duration was measured. */
+    minutes: number | null;
+    placeholder?: boolean;
+}
+export declare const MODEL_RATES: Record<string, ModelRate>;
+export declare const DESKTOP_RATE: DesktopRate;
+/** Round a USD figure to 6 decimals so a float-accumulated total never carries spurious
+ *  precision. This mirrors the SPIRIT of the terminal ledger's private roundUsd (6dp) without
+ *  importing it — pricing stays a standalone pure module. */
+export declare function round6(n: number): number;
+/**
+ * Estimate one actor lane's model-token cost from its trace tokenUsage + model id. Deterministic;
+ * the rate table is injectable (tests pass a fake sheet). Returns a DECLARED-ABSENT estimate
+ * (estimatedCostUsd: null + a reason) for a missing rate or missing usage — never a guessed cost.
+ */
+export declare function estimateActorCost(tokenUsage: ActorTokenUsage | undefined, modelId: string | undefined, rates?: Record<string, ModelRate>): ActorEstimatedCost;
+/**
+ * Estimate the E2B desktop-minute cost from a host-side create->teardown span (minutes). The rate
+ * is injectable. Returns a DECLARED-ABSENT estimate (null + "no_duration") when no duration was
+ * measured (no sandbox / unmeasurable span) — never a guessed 0.
+ */
+export declare function estimateDesktopCost(minutes: number | undefined, rate?: DesktopRate): DesktopCostEstimate;

package/dist/pricing.js

@@ -0,0 +1,100 @@
+// OPERATOR-EDITABLE ESTIMATES — NOT authoritative prices. Providers change pricing without
+// notice. When they do, update BOTH the number AND the `asOf` date on the affected entry.
+// Every dollar figure humanish derives from this table is surfaced/persisted as an ESTIMATE,
+// labeled "estimated (rates as of <asOf>)", and is NEVER presented as an exact charge.
+//
+// This module is PURE (node builtins only, no deps) and deterministic: the two estimator
+// functions take an OPTIONAL injected rate table/rate so tests drive assertions with a fake
+// sheet and never depend on the live numbers below. An UNKNOWN model/desktop rate yields a
+// DECLARED-ABSENT estimate (estimatedCostUsd: null + a reason), NEVER a guessed or silent-zero
+// cost (invariant 5). A bare `costUsd` elsewhere in the contract means a provider actually
+// billed that amount; the token-derived estimate here always lives under `estimatedCostUsd`
+// so a reader can never confuse an estimate for an authoritative charge (invariant 6).
+export const PRICING_SCHEMA = "humanish.pricing.v1";
+export const ACTOR_ESTIMATED_COST_SCHEMA = "humanish.actor-estimated-cost.v1";
+// Per-model rates, keyed on the model id that lands in trace.ids.model (lookup is
+// case-insensitive on a trimmed id). An id NOT present here is DECLARED ABSENT, never guessed.
+export const MODEL_RATES = {
+    // OpenAI computer-use-preview (the classic CUA model). ~$3 / 1M input, ~$12 / 1M output.
+    // source: openai.com/api/pricing (verify — providers change without notice).
+    "computer-use-preview": {
+        inputUsdPerToken: 3e-6,
+        outputUsdPerToken: 12e-6,
+        asOf: "2026-08-01",
+        source: "openai.com/api/pricing (computer-use-preview)"
+    },
+    // gpt-5.5 = the shipped CUA default (DEFAULT_OPENAI_CU_MODEL). PLACEHOLDER shaped like a
+    // GPT-5-class rate (~$1.25 / 1M input, ~$10 / 1M output) until confirmed against the live sheet.
+    "gpt-5.5": {
+        inputUsdPerToken: 1.25e-6,
+        outputUsdPerToken: 10e-6,
+        asOf: "2026-08-01",
+        source: "PLACEHOLDER — confirm at openai.com/api/pricing",
+        placeholder: true
+    }
+};
+// E2B desktop sandbox compute, billed per-second by vCPU+RAM. PLACEHOLDER ~ $0.10 / hr for a
+// ~2 vCPU desktop => ~$0.00167 / minute. Confirm at e2b.dev/pricing.
+export const DESKTOP_RATE = {
+    usdPerMinute: 0.00167,
+    asOf: "2026-08-01",
+    source: "PLACEHOLDER — confirm at e2b.dev/pricing",
+    placeholder: true
+};
+/** Round a USD figure to 6 decimals so a float-accumulated total never carries spurious
+ *  precision. This mirrors the SPIRIT of the terminal ledger's private roundUsd (6dp) without
+ *  importing it — pricing stays a standalone pure module. */
+export function round6(n) {
+    return Math.round(n * 1e6) / 1e6;
+}
+/**
+ * Estimate one actor lane's model-token cost from its trace tokenUsage + model id. Deterministic;
+ * the rate table is injectable (tests pass a fake sheet). Returns a DECLARED-ABSENT estimate
+ * (estimatedCostUsd: null + a reason) for a missing rate or missing usage — never a guessed cost.
+ */
+export function estimateActorCost(tokenUsage, modelId, rates = MODEL_RATES) {
+    if (!tokenUsage || (tokenUsage.input === undefined && tokenUsage.output === undefined)) {
+        return { schema: ACTOR_ESTIMATED_COST_SCHEMA, estimatedCostUsd: null, reason: "no_token_usage", ratesAsOf: null };
+    }
+    const rate = modelId ? rates[modelId.trim().toLowerCase()] : undefined;
+    if (!rate) {
+        return {
+            schema: ACTOR_ESTIMATED_COST_SCHEMA,
+            estimatedCostUsd: null,
+            reason: "no_rate_for_model",
+            ratesAsOf: null,
+            ...(modelId ? { modelId } : {})
+        };
+    }
+    const inTok = tokenUsage.input ?? 0;
+    const outTok = tokenUsage.output ?? 0;
+    const inputUsd = round6(inTok * rate.inputUsdPerToken);
+    const outputUsd = round6(outTok * rate.outputUsdPerToken);
+    return {
+        schema: ACTOR_ESTIMATED_COST_SCHEMA,
+        estimatedCostUsd: round6(inputUsd + outputUsd),
+        ratesAsOf: rate.asOf,
+        source: rate.source,
+        ...(modelId ? { modelId } : {}),
+        ...(rate.placeholder ? { placeholder: true } : {}),
+        breakdown: { inputUsd, outputUsd, inputTokens: inTok, outputTokens: outTok }
+    };
+}
+/**
+ * Estimate the E2B desktop-minute cost from a host-side create->teardown span (minutes). The rate
+ * is injectable. Returns a DECLARED-ABSENT estimate (null + "no_duration") when no duration was
+ * measured (no sandbox / unmeasurable span) — never a guessed 0.
+ */
+export function estimateDesktopCost(minutes, rate = DESKTOP_RATE) {
+    if (minutes === undefined || !(minutes >= 0)) {
+        return { estimatedCostUsd: null, reason: "no_duration", ratesAsOf: null, minutes: null };
+    }
+    return {
+        estimatedCostUsd: round6(minutes * rate.usdPerMinute),
+        ratesAsOf: rate.asOf,
+        source: rate.source,
+        minutes: round6(minutes),
+        ...(rate.placeholder ? { placeholder: true } : {})
+    };
+}
+//# sourceMappingURL=pricing.js.map

package/dist/pricing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pricing.js","sourceRoot":"","sources":["../src/pricing.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAC3F,0FAA0F;AAC1F,6FAA6F;AAC7F,uFAAuF;AACvF,EAAE;AACF,yFAAyF;AACzF,4FAA4F;AAC5F,2FAA2F;AAC3F,+FAA+F;AAC/F,2FAA2F;AAC3F,4FAA4F;AAC5F,uFAAuF;AAMvF,MAAM,CAAC,MAAM,cAAc,GAAG,qBAAqB,CAAC;AACpD,MAAM,CAAC,MAAM,2BAA2B,GAAG,kCAAkC,CAAC;AA0D9E,kFAAkF;AAClF,+FAA+F;AAC/F,MAAM,CAAC,MAAM,WAAW,GAA8B;IACpD,yFAAyF;IACzF,6EAA6E;IAC7E,sBAAsB,EAAE;QACtB,gBAAgB,EAAE,IAAI;QACtB,iBAAiB,EAAE,KAAK;QACxB,IAAI,EAAE,YAAY;QAClB,MAAM,EAAE,+CAA+C;KACxD;IACD,yFAAyF;IACzF,iGAAiG;IACjG,SAAS,EAAE;QACT,gBAAgB,EAAE,OAAO;QACzB,iBAAiB,EAAE,KAAK;QACxB,IAAI,EAAE,YAAY;QAClB,MAAM,EAAE,iDAAiD;QACzD,WAAW,EAAE,IAAI;KAClB;CACF,CAAC;AAEF,6FAA6F;AAC7F,qEAAqE;AACrE,MAAM,CAAC,MAAM,YAAY,GAAgB;IACvC,YAAY,EAAE,OAAO;IACrB,IAAI,EAAE,YAAY;IAClB,MAAM,EAAE,0CAA0C;IAClD,WAAW,EAAE,IAAI;CAClB,CAAC;AAEF;;6DAE6D;AAC7D,MAAM,UAAU,MAAM,CAAC,CAAS;IAC9B,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC;AACnC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAC/B,UAAuC,EACvC,OAA2B,EAC3B,QAAmC,WAAW;IAE9C,IAAI,CAAC,UAAU,IAAI,CAAC,UAAU,CAAC,KAAK,KAAK,SAAS,IAAI,UAAU,CAAC,MAAM,KAAK,SAAS,CAAC,EAAE,CAAC;QACvF,OAAO,EAAE,MAAM,EAAE,2BAA2B,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,EAAE,gBAAgB,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IACpH,CAAC;IACD,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACvE,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO;YACL,MAAM,EAAE,2BAA2B;YACnC,gBAAgB,EAAE,IAAI;YACtB,MAAM,EAAE,mBAAmB;YAC3B,SAAS,EAAE,IAAI;YACf,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAChC,CAAC;IACJ,CAAC;IACD,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,IAAI,CAAC,CAAC;IACpC,MAAM,MAAM,GAAG,UAAU,CAAC,MAAM,IAAI,CAAC,CAAC;IACtC,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,GAAG,IAAI,CAAC,gBAAgB,CAAC,CAAC;IACvD,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC,iBAAiB,CAAC,CAAC;IAC1D,OAAO;QACL,MAAM,EAAE,2BAA2B;QACnC,gBAAgB,EAAE,MAAM,CAAC,QAAQ,GAAG,SAAS,CAAC;QAC9C,SAAS,EAAE,IAAI,CAAC,IAAI;QACpB,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/B,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAClD,SAAS,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,WAAW,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE;KAC7E,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAA2B,EAC3B,OAAoB,YAAY;IAEhC,IAAI,OAAO,KAAK,SAAS,IAAI,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,EAAE,CAAC;QAC7C,OAAO,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC3F,CAAC;IACD,OAAO;QACL,gBAAgB,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC,YAAY,CAAC;QACrD,SAAS,EAAE,IAAI,CAAC,IAAI;QACpB,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC;QACxB,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACnD,CAAC;AACJ,CAAC"}