runcycles 0.1.0

package/dist/index.js

@@ -0,0 +1,1374 @@
+// src/constants.ts
+var API_KEY_HEADER = "X-Cycles-API-Key";
+var IDEMPOTENCY_KEY_HEADER = "X-Idempotency-Key";
+var RESERVATIONS_PATH = "/v1/reservations";
+var DECIDE_PATH = "/v1/decide";
+var BALANCES_PATH = "/v1/balances";
+var EVENTS_PATH = "/v1/events";
+
+// src/mappers.ts
+function stripUndefined(obj) {
+  const result = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (value !== void 0) {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+function metricsToWire(metrics) {
+  return stripUndefined({
+    tokens_input: metrics.tokensInput,
+    tokens_output: metrics.tokensOutput,
+    latency_ms: metrics.latencyMs,
+    model_version: metrics.modelVersion,
+    custom: metrics.custom
+  });
+}
+function capsFromWire(wire) {
+  if (!wire) return void 0;
+  return stripUndefined({
+    maxTokens: wire.max_tokens,
+    maxStepsRemaining: wire.max_steps_remaining,
+    toolAllowlist: wire.tool_allowlist,
+    toolDenylist: wire.tool_denylist,
+    cooldownMs: wire.cooldown_ms
+  });
+}
+function amountFromWire(wire) {
+  if (!wire) return void 0;
+  return { unit: wire.unit, amount: wire.amount };
+}
+function signedAmountFromWire(wire) {
+  if (!wire) return void 0;
+  return { unit: wire.unit, amount: wire.amount };
+}
+function balanceFromWire(wire) {
+  return {
+    scope: wire.scope,
+    scopePath: wire.scope_path,
+    remaining: signedAmountFromWire(wire.remaining),
+    reserved: amountFromWire(wire.reserved),
+    spent: amountFromWire(wire.spent),
+    allocated: amountFromWire(wire.allocated),
+    debt: amountFromWire(wire.debt),
+    overdraftLimit: amountFromWire(wire.overdraft_limit),
+    isOverLimit: wire.is_over_limit
+  };
+}
+function balancesFromWire(wire) {
+  if (!wire) return void 0;
+  return wire.map((b) => balanceFromWire(b));
+}
+function reservationCreateResponseFromWire(wire) {
+  return {
+    decision: wire.decision,
+    reservationId: wire.reservation_id,
+    affectedScopes: wire.affected_scopes ?? [],
+    expiresAtMs: wire.expires_at_ms,
+    scopePath: wire.scope_path,
+    reserved: amountFromWire(wire.reserved),
+    caps: capsFromWire(wire.caps),
+    reasonCode: wire.reason_code,
+    retryAfterMs: wire.retry_after_ms,
+    balances: balancesFromWire(wire.balances)
+  };
+}
+function commitResponseFromWire(wire) {
+  return {
+    status: wire.status,
+    charged: amountFromWire(wire.charged),
+    released: amountFromWire(wire.released),
+    balances: balancesFromWire(wire.balances)
+  };
+}
+function releaseResponseFromWire(wire) {
+  return {
+    status: wire.status,
+    released: amountFromWire(wire.released),
+    balances: balancesFromWire(wire.balances)
+  };
+}
+function reservationExtendResponseFromWire(wire) {
+  return {
+    status: wire.status,
+    expiresAtMs: wire.expires_at_ms,
+    balances: balancesFromWire(wire.balances)
+  };
+}
+function decisionResponseFromWire(wire) {
+  return stripUndefined({
+    decision: wire.decision,
+    caps: capsFromWire(wire.caps),
+    reasonCode: wire.reason_code,
+    retryAfterMs: wire.retry_after_ms,
+    affectedScopes: wire.affected_scopes
+  });
+}
+function eventCreateResponseFromWire(wire) {
+  return {
+    status: wire.status,
+    eventId: wire.event_id,
+    balances: balancesFromWire(wire.balances)
+  };
+}
+function subjectFromWire(wire) {
+  const result = {};
+  if (wire.tenant !== void 0) result.tenant = wire.tenant;
+  if (wire.workspace !== void 0) result.workspace = wire.workspace;
+  if (wire.app !== void 0) result.app = wire.app;
+  if (wire.workflow !== void 0) result.workflow = wire.workflow;
+  if (wire.agent !== void 0) result.agent = wire.agent;
+  if (wire.toolset !== void 0) result.toolset = wire.toolset;
+  if (wire.dimensions !== void 0) result.dimensions = wire.dimensions;
+  return result;
+}
+function actionFromWire(wire) {
+  const result = {
+    kind: wire.kind,
+    name: wire.name
+  };
+  if (wire.tags !== void 0) result.tags = wire.tags;
+  return result;
+}
+function reservationDetailFromWire(wire) {
+  return {
+    reservationId: wire.reservation_id,
+    status: wire.status,
+    subject: subjectFromWire(wire.subject),
+    action: actionFromWire(wire.action),
+    reserved: amountFromWire(wire.reserved),
+    createdAtMs: wire.created_at_ms,
+    expiresAtMs: wire.expires_at_ms,
+    scopePath: wire.scope_path,
+    affectedScopes: wire.affected_scopes,
+    idempotencyKey: wire.idempotency_key,
+    committed: amountFromWire(wire.committed),
+    finalizedAtMs: wire.finalized_at_ms,
+    metadata: wire.metadata
+  };
+}
+function reservationSummaryFromWire(wire) {
+  return {
+    reservationId: wire.reservation_id,
+    status: wire.status,
+    subject: subjectFromWire(wire.subject),
+    action: actionFromWire(wire.action),
+    reserved: amountFromWire(wire.reserved),
+    createdAtMs: wire.created_at_ms,
+    expiresAtMs: wire.expires_at_ms,
+    scopePath: wire.scope_path,
+    affectedScopes: wire.affected_scopes,
+    idempotencyKey: wire.idempotency_key
+  };
+}
+function reservationListResponseFromWire(wire) {
+  const reservations = wire.reservations.map(
+    (r) => reservationSummaryFromWire(r)
+  );
+  return {
+    reservations,
+    nextCursor: wire.next_cursor,
+    hasMore: wire.has_more
+  };
+}
+function balanceResponseFromWire(wire) {
+  return {
+    balances: balancesFromWire(wire.balances) ?? [],
+    nextCursor: wire.next_cursor,
+    hasMore: wire.has_more
+  };
+}
+function errorResponseFromWire(wire) {
+  if (typeof wire.error !== "string" || typeof wire.message !== "string" || typeof wire.request_id !== "string") {
+    return void 0;
+  }
+  return {
+    error: wire.error,
+    message: wire.message,
+    requestId: wire.request_id,
+    details: wire.details
+  };
+}
+function actionToWire(action) {
+  return stripUndefined({
+    kind: action.kind,
+    name: action.name,
+    tags: action.tags
+  });
+}
+function subjectToWire(subject) {
+  return stripUndefined({
+    tenant: subject.tenant,
+    workspace: subject.workspace,
+    app: subject.app,
+    workflow: subject.workflow,
+    agent: subject.agent,
+    toolset: subject.toolset,
+    dimensions: subject.dimensions
+  });
+}
+function reservationCreateRequestToWire(req) {
+  return stripUndefined({
+    idempotency_key: req.idempotencyKey,
+    subject: subjectToWire(req.subject),
+    action: actionToWire(req.action),
+    estimate: req.estimate,
+    ttl_ms: req.ttlMs,
+    grace_period_ms: req.gracePeriodMs,
+    overage_policy: req.overagePolicy,
+    dry_run: req.dryRun,
+    metadata: req.metadata
+  });
+}
+function commitRequestToWire(req) {
+  return stripUndefined({
+    idempotency_key: req.idempotencyKey,
+    actual: req.actual,
+    metrics: req.metrics ? metricsToWire(req.metrics) : void 0,
+    metadata: req.metadata
+  });
+}
+function releaseRequestToWire(req) {
+  return stripUndefined({
+    idempotency_key: req.idempotencyKey,
+    reason: req.reason
+  });
+}
+function reservationExtendRequestToWire(req) {
+  return stripUndefined({
+    idempotency_key: req.idempotencyKey,
+    extend_by_ms: req.extendByMs,
+    metadata: req.metadata
+  });
+}
+function decisionRequestToWire(req) {
+  return stripUndefined({
+    idempotency_key: req.idempotencyKey,
+    subject: subjectToWire(req.subject),
+    action: actionToWire(req.action),
+    estimate: req.estimate,
+    metadata: req.metadata
+  });
+}
+function eventCreateRequestToWire(req) {
+  return stripUndefined({
+    idempotency_key: req.idempotencyKey,
+    subject: subjectToWire(req.subject),
+    action: actionToWire(req.action),
+    actual: req.actual,
+    overage_policy: req.overagePolicy,
+    metrics: req.metrics ? metricsToWire(req.metrics) : void 0,
+    client_time_ms: req.clientTimeMs,
+    metadata: req.metadata
+  });
+}
+
+// src/response.ts
+var CyclesResponse = class _CyclesResponse {
+  status;
+  body;
+  errorMessage;
+  headers;
+  _isTransportError;
+  transportError;
+  constructor(options) {
+    this.status = options.status;
+    this.body = options.body;
+    this.errorMessage = options.errorMessage;
+    this.headers = options.headers ?? {};
+    this._isTransportError = options.isTransportError ?? false;
+    this.transportError = options.transportError;
+  }
+  static success(status, body, headers) {
+    return new _CyclesResponse({ status, body, headers });
+  }
+  static httpError(status, errorMessage, body, headers) {
+    return new _CyclesResponse({ status, body, errorMessage, headers });
+  }
+  static transportError(err) {
+    return new _CyclesResponse({
+      status: -1,
+      errorMessage: err.message,
+      isTransportError: true,
+      transportError: err
+    });
+  }
+  get requestId() {
+    return this.headers["x-request-id"];
+  }
+  get rateLimitRemaining() {
+    const val = this.headers["x-ratelimit-remaining"];
+    return val !== void 0 ? parseInt(val, 10) : void 0;
+  }
+  get rateLimitReset() {
+    const val = this.headers["x-ratelimit-reset"];
+    return val !== void 0 ? parseInt(val, 10) : void 0;
+  }
+  get cyclesTenant() {
+    return this.headers["x-cycles-tenant"];
+  }
+  get isSuccess() {
+    return this.status >= 200 && this.status < 300;
+  }
+  get isClientError() {
+    return this.status >= 400 && this.status < 500;
+  }
+  get isServerError() {
+    return this.status >= 500 && this.status < 600;
+  }
+  get isTransportError() {
+    return this._isTransportError;
+  }
+  getBodyAttribute(key) {
+    if (this.body && key in this.body) {
+      return this.body[key];
+    }
+    return void 0;
+  }
+  getErrorResponse() {
+    if (this.body && typeof this.body === "object") {
+      return errorResponseFromWire(this.body);
+    }
+    return void 0;
+  }
+};
+
+// src/client.ts
+var RESPONSE_HEADERS = [
+  "x-request-id",
+  "x-ratelimit-remaining",
+  "x-ratelimit-reset",
+  "x-cycles-tenant"
+];
+var BALANCE_FILTER_PARAMS = /* @__PURE__ */ new Set([
+  "tenant",
+  "workspace",
+  "app",
+  "workflow",
+  "agent",
+  "toolset"
+]);
+function extractResponseHeaders(resp) {
+  const result = {};
+  for (const name of RESPONSE_HEADERS) {
+    const val = resp.headers.get(name);
+    if (val !== null) {
+      result[name] = val;
+    }
+  }
+  return result;
+}
+var CyclesClient = class {
+  _config;
+  constructor(config) {
+    this._config = config;
+  }
+  get config() {
+    return this._config;
+  }
+  async createReservation(request) {
+    return this._post(RESERVATIONS_PATH, request);
+  }
+  async commitReservation(reservationId, request) {
+    return this._post(
+      `${RESERVATIONS_PATH}/${reservationId}/commit`,
+      request
+    );
+  }
+  async releaseReservation(reservationId, request) {
+    return this._post(
+      `${RESERVATIONS_PATH}/${reservationId}/release`,
+      request
+    );
+  }
+  async extendReservation(reservationId, request) {
+    return this._post(
+      `${RESERVATIONS_PATH}/${reservationId}/extend`,
+      request
+    );
+  }
+  async decide(request) {
+    return this._post(DECIDE_PATH, request);
+  }
+  async listReservations(params) {
+    return this._get(RESERVATIONS_PATH, params);
+  }
+  async getReservation(reservationId) {
+    return this._get(`${RESERVATIONS_PATH}/${reservationId}`);
+  }
+  async getBalances(params) {
+    const hasFilter = Object.keys(params).some(
+      (k) => BALANCE_FILTER_PARAMS.has(k)
+    );
+    if (!hasFilter) {
+      throw new Error(
+        "getBalances requires at least one subject filter (tenant, workspace, app, workflow, agent, or toolset)"
+      );
+    }
+    return this._get(BALANCES_PATH, params);
+  }
+  async createEvent(request) {
+    return this._post(EVENTS_PATH, request);
+  }
+  async _post(path, body) {
+    try {
+      const headers = {
+        "Content-Type": "application/json",
+        [API_KEY_HEADER]: this._config.apiKey
+      };
+      const idemKey = body.idempotency_key;
+      if (typeof idemKey === "string") {
+        headers[IDEMPOTENCY_KEY_HEADER] = idemKey;
+      }
+      const url = `${this._config.baseUrl}${path}`;
+      const resp = await fetch(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(
+          this._config.connectTimeout + this._config.readTimeout
+        )
+      });
+      return this._handleResponse(resp);
+    } catch (err) {
+      return CyclesResponse.transportError(
+        err instanceof Error ? err : new Error(String(err))
+      );
+    }
+  }
+  async _get(path, params) {
+    try {
+      let url = `${this._config.baseUrl}${path}`;
+      if (params && Object.keys(params).length > 0) {
+        const qs = new URLSearchParams(params).toString();
+        url = `${url}?${qs}`;
+      }
+      const resp = await fetch(url, {
+        method: "GET",
+        headers: {
+          [API_KEY_HEADER]: this._config.apiKey
+        },
+        signal: AbortSignal.timeout(
+          this._config.connectTimeout + this._config.readTimeout
+        )
+      });
+      return this._handleResponse(resp);
+    } catch (err) {
+      return CyclesResponse.transportError(
+        err instanceof Error ? err : new Error(String(err))
+      );
+    }
+  }
+  async _handleResponse(resp) {
+    let body;
+    try {
+      body = await resp.json();
+    } catch {
+      body = void 0;
+    }
+    const headers = extractResponseHeaders(resp);
+    if (resp.status >= 200 && resp.status < 300) {
+      return CyclesResponse.success(resp.status, body ?? {}, headers);
+    }
+    let errorMsg;
+    if (body && typeof body === "object") {
+      errorMsg = body.message ?? body.error ?? void 0;
+    }
+    return CyclesResponse.httpError(
+      resp.status,
+      errorMsg ?? resp.statusText ?? "Unknown error",
+      body,
+      headers
+    );
+  }
+};
+
+// src/config.ts
+var CyclesConfig = class _CyclesConfig {
+  baseUrl;
+  apiKey;
+  tenant;
+  workspace;
+  app;
+  workflow;
+  agent;
+  toolset;
+  connectTimeout;
+  readTimeout;
+  retryEnabled;
+  retryMaxAttempts;
+  retryInitialDelay;
+  retryMultiplier;
+  retryMaxDelay;
+  constructor(options) {
+    this.baseUrl = options.baseUrl;
+    this.apiKey = options.apiKey;
+    this.tenant = options.tenant;
+    this.workspace = options.workspace;
+    this.app = options.app;
+    this.workflow = options.workflow;
+    this.agent = options.agent;
+    this.toolset = options.toolset;
+    this.connectTimeout = options.connectTimeout ?? 2e3;
+    this.readTimeout = options.readTimeout ?? 5e3;
+    this.retryEnabled = options.retryEnabled ?? true;
+    this.retryMaxAttempts = options.retryMaxAttempts ?? 5;
+    this.retryInitialDelay = options.retryInitialDelay ?? 500;
+    this.retryMultiplier = options.retryMultiplier ?? 2;
+    this.retryMaxDelay = options.retryMaxDelay ?? 3e4;
+  }
+  static fromEnv(prefix = "CYCLES_") {
+    const baseUrl = process.env[`${prefix}BASE_URL`];
+    const apiKey = process.env[`${prefix}API_KEY`];
+    if (!baseUrl) {
+      throw new Error(`${prefix}BASE_URL environment variable is required`);
+    }
+    if (!apiKey) {
+      throw new Error(`${prefix}API_KEY environment variable is required`);
+    }
+    return new _CyclesConfig({
+      baseUrl,
+      apiKey,
+      tenant: process.env[`${prefix}TENANT`],
+      workspace: process.env[`${prefix}WORKSPACE`],
+      app: process.env[`${prefix}APP`],
+      workflow: process.env[`${prefix}WORKFLOW`],
+      agent: process.env[`${prefix}AGENT`],
+      toolset: process.env[`${prefix}TOOLSET`],
+      connectTimeout: optionalFloat(process.env[`${prefix}CONNECT_TIMEOUT`], 2e3),
+      readTimeout: optionalFloat(process.env[`${prefix}READ_TIMEOUT`], 5e3),
+      retryEnabled: process.env[`${prefix}RETRY_ENABLED`]?.toLowerCase() !== "false",
+      retryMaxAttempts: optionalInt(process.env[`${prefix}RETRY_MAX_ATTEMPTS`], 5),
+      retryInitialDelay: optionalFloat(process.env[`${prefix}RETRY_INITIAL_DELAY`], 500),
+      retryMultiplier: optionalFloat(process.env[`${prefix}RETRY_MULTIPLIER`], 2),
+      retryMaxDelay: optionalFloat(process.env[`${prefix}RETRY_MAX_DELAY`], 3e4)
+    });
+  }
+};
+function optionalInt(val, fallback) {
+  return val !== void 0 ? parseInt(val, 10) : fallback;
+}
+function optionalFloat(val, fallback) {
+  return val !== void 0 ? parseFloat(val) : fallback;
+}
+
+// src/lifecycle.ts
+import { randomUUID } from "crypto";
+
+// src/context.ts
+import { AsyncLocalStorage } from "async_hooks";
+var storage = new AsyncLocalStorage();
+function getCyclesContext() {
+  return storage.getStore();
+}
+function runWithContext(ctx, fn) {
+  return storage.run(ctx, fn);
+}
+
+// src/exceptions.ts
+var CyclesError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "CyclesError";
+  }
+};
+var CyclesProtocolError = class extends CyclesError {
+  status;
+  errorCode;
+  reasonCode;
+  retryAfterMs;
+  requestId;
+  details;
+  constructor(message, options = {}) {
+    super(message);
+    this.name = "CyclesProtocolError";
+    this.status = options.status ?? 0;
+    this.errorCode = options.errorCode;
+    this.reasonCode = options.reasonCode;
+    this.retryAfterMs = options.retryAfterMs;
+    this.requestId = options.requestId;
+    this.details = options.details;
+  }
+  isBudgetExceeded() {
+    return this.errorCode === "BUDGET_EXCEEDED";
+  }
+  isOverdraftLimitExceeded() {
+    return this.errorCode === "OVERDRAFT_LIMIT_EXCEEDED";
+  }
+  isDebtOutstanding() {
+    return this.errorCode === "DEBT_OUTSTANDING";
+  }
+  isReservationExpired() {
+    return this.errorCode === "RESERVATION_EXPIRED";
+  }
+  isReservationFinalized() {
+    return this.errorCode === "RESERVATION_FINALIZED";
+  }
+  isIdempotencyMismatch() {
+    return this.errorCode === "IDEMPOTENCY_MISMATCH";
+  }
+  isUnitMismatch() {
+    return this.errorCode === "UNIT_MISMATCH";
+  }
+  isRetryable() {
+    return this.errorCode === "INTERNAL_ERROR" || this.errorCode === "UNKNOWN" || this.status >= 500;
+  }
+};
+var BudgetExceededError = class extends CyclesProtocolError {
+  constructor(message, options = {}) {
+    super(message, options);
+    this.name = "BudgetExceededError";
+  }
+};
+var OverdraftLimitExceededError = class extends CyclesProtocolError {
+  constructor(message, options = {}) {
+    super(message, options);
+    this.name = "OverdraftLimitExceededError";
+  }
+};
+var DebtOutstandingError = class extends CyclesProtocolError {
+  constructor(message, options = {}) {
+    super(message, options);
+    this.name = "DebtOutstandingError";
+  }
+};
+var ReservationExpiredError = class extends CyclesProtocolError {
+  constructor(message, options = {}) {
+    super(message, options);
+    this.name = "ReservationExpiredError";
+  }
+};
+var ReservationFinalizedError = class extends CyclesProtocolError {
+  constructor(message, options = {}) {
+    super(message, options);
+    this.name = "ReservationFinalizedError";
+  }
+};
+var CyclesTransportError = class extends CyclesError {
+  cause;
+  constructor(message, options) {
+    super(message);
+    this.name = "CyclesTransportError";
+    this.cause = options?.cause;
+  }
+};
+
+// src/errors.ts
+function buildProtocolException(prefix, response) {
+  const errorResp = response.getErrorResponse();
+  let errorCode;
+  let reasonCode;
+  let message = prefix;
+  let requestId;
+  let details;
+  if (errorResp) {
+    errorCode = errorResp.error;
+    requestId = errorResp.requestId;
+    details = errorResp.details;
+    if (errorResp.message) {
+      message = `${prefix}: ${errorResp.message}`;
+    }
+  } else {
+    const rawError = response.getBodyAttribute("error");
+    if (typeof rawError === "string") {
+      errorCode = rawError;
+    }
+    if (response.errorMessage) {
+      message = `${prefix}: ${response.errorMessage}`;
+    }
+  }
+  reasonCode = response.getBodyAttribute("reason_code");
+  if (reasonCode === void 0 && errorCode !== void 0) {
+    reasonCode = errorCode;
+  }
+  const retryRaw = response.getBodyAttribute("retry_after_ms");
+  const retryAfterMs = retryRaw !== void 0 ? Number(retryRaw) : void 0;
+  const opts = {
+    status: response.status,
+    errorCode,
+    reasonCode,
+    retryAfterMs,
+    requestId,
+    details
+  };
+  switch (errorCode) {
+    case "BUDGET_EXCEEDED":
+      return new BudgetExceededError(message, opts);
+    case "OVERDRAFT_LIMIT_EXCEEDED":
+      return new OverdraftLimitExceededError(message, opts);
+    case "DEBT_OUTSTANDING":
+      return new DebtOutstandingError(message, opts);
+    case "RESERVATION_EXPIRED":
+      return new ReservationExpiredError(message, opts);
+    case "RESERVATION_FINALIZED":
+      return new ReservationFinalizedError(message, opts);
+    default:
+      return new CyclesProtocolError(message, opts);
+  }
+}
+
+// src/validation.ts
+function validateSubject(subject) {
+  if (subject === void 0) return;
+  const hasField = !!(subject.tenant || subject.workspace || subject.app || subject.workflow || subject.agent || subject.toolset);
+  if (!hasField) {
+    throw new Error(
+      "Subject must have at least one standard field (tenant, workspace, app, workflow, agent, or toolset)"
+    );
+  }
+}
+function validateNonNegative(value, name) {
+  if (value < 0) {
+    throw new Error(`${name} must be non-negative, got ${value}`);
+  }
+}
+function validateTtlMs(ttlMs) {
+  if (ttlMs < 1e3 || ttlMs > 864e5) {
+    throw new Error(`ttl_ms must be between 1000 and 86400000, got ${ttlMs}`);
+  }
+}
+function validateGracePeriodMs(gracePeriodMs) {
+  if (gracePeriodMs !== void 0 && (gracePeriodMs < 0 || gracePeriodMs > 6e4)) {
+    throw new Error(`grace_period_ms must be between 0 and 60000, got ${gracePeriodMs}`);
+  }
+}
+function validateExtendByMs(extendByMs) {
+  if (extendByMs < 1 || extendByMs > 864e5) {
+    throw new Error(`extend_by_ms must be between 1 and 86400000, got ${extendByMs}`);
+  }
+}
+
+// src/lifecycle.ts
+function evaluateAmount(expr, args) {
+  if (typeof expr === "function") {
+    return expr(...args);
+  }
+  return expr;
+}
+function evaluateActual(expr, result, estimate, useEstimateFallback) {
+  if (expr !== void 0) {
+    if (typeof expr === "function") {
+      return expr(result);
+    }
+    return expr;
+  }
+  if (useEstimateFallback) {
+    return estimate;
+  }
+  throw new Error(
+    "actual expression is required when useEstimateIfActualNotProvided is false"
+  );
+}
+function buildReservationBody(cfg, estimate, defaultSubject) {
+  validateNonNegative(estimate, "estimate");
+  const ttlMs = cfg.ttlMs ?? 6e4;
+  validateTtlMs(ttlMs);
+  const subject = {};
+  for (const field of [
+    "tenant",
+    "workspace",
+    "app",
+    "workflow",
+    "agent",
+    "toolset"
+  ]) {
+    const val = cfg[field] ?? defaultSubject[field];
+    if (val) {
+      subject[field] = val;
+    }
+  }
+  if (cfg.dimensions) {
+    subject.dimensions = cfg.dimensions;
+  }
+  validateSubject(subject);
+  const action = {
+    kind: cfg.actionKind ?? "unknown",
+    name: cfg.actionName ?? "unknown"
+  };
+  if (cfg.actionTags) {
+    action.tags = cfg.actionTags;
+  }
+  const unit = cfg.unit ?? "USD_MICROCENTS";
+  const body = {
+    idempotency_key: randomUUID(),
+    subject,
+    action,
+    estimate: { unit, amount: estimate },
+    ttl_ms: ttlMs,
+    overage_policy: cfg.overagePolicy ?? "REJECT"
+  };
+  validateGracePeriodMs(cfg.gracePeriodMs);
+  if (cfg.gracePeriodMs !== void 0) {
+    body.grace_period_ms = cfg.gracePeriodMs;
+  }
+  if (cfg.dryRun) {
+    body.dry_run = true;
+  }
+  return body;
+}
+function buildCommitBody(actual, unit, metrics, metadata) {
+  const body = {
+    idempotency_key: randomUUID(),
+    actual: { unit, amount: actual }
+  };
+  if (metrics && !isMetricsEmpty(metrics)) {
+    body.metrics = metricsToWire(metrics);
+  }
+  if (metadata) {
+    body.metadata = metadata;
+  }
+  return body;
+}
+function isMetricsEmpty(metrics) {
+  return metrics.tokensInput === void 0 && metrics.tokensOutput === void 0 && metrics.latencyMs === void 0 && metrics.modelVersion === void 0 && !metrics.custom;
+}
+function buildReleaseBody(reason) {
+  return { idempotency_key: randomUUID(), reason };
+}
+function buildExtendBody(extendByMs) {
+  validateExtendByMs(extendByMs);
+  return { idempotency_key: randomUUID(), extend_by_ms: extendByMs };
+}
+var AsyncCyclesLifecycle = class {
+  _client;
+  _retryEngine;
+  _defaultSubject;
+  constructor(client, retryEngine, defaultSubject) {
+    this._client = client;
+    this._retryEngine = retryEngine;
+    this._retryEngine.setClient(client);
+    this._defaultSubject = defaultSubject;
+  }
+  async execute(fn, args, cfg) {
+    const estimate = evaluateAmount(cfg.estimate, args);
+    const createBody = buildReservationBody(cfg, estimate, this._defaultSubject);
+    const resT1 = performance.now();
+    const resResponse = await this._client.createReservation(createBody);
+    if (!resResponse.isSuccess) {
+      throw buildProtocolException("Failed to create reservation", resResponse);
+    }
+    const resResult = reservationCreateResponseFromWire(
+      resResponse.body
+    );
+    const resT2 = performance.now();
+    const decision = resResult.decision;
+    const reservationId = resResult.reservationId;
+    const reasonCode = resResult.reasonCode;
+    if (cfg.dryRun) {
+      if (decision === "DENY") {
+        throw buildProtocolException("Dry-run denied", resResponse);
+      }
+      return {
+        decision,
+        caps: resResult.caps,
+        affectedScopes: resResult.affectedScopes,
+        scopePath: resResult.scopePath,
+        reserved: resResult.reserved,
+        balances: resResult.balances,
+        reasonCode,
+        retryAfterMs: resResult.retryAfterMs
+      };
+    }
+    if (decision === "DENY") {
+      throw buildProtocolException("Reservation denied", resResponse);
+    }
+    if (!reservationId) {
+      throw new CyclesProtocolError(
+        "Reservation successful but reservation_id missing",
+        { status: resResponse.status }
+      );
+    }
+    const unit = cfg.unit ?? "USD_MICROCENTS";
+    const ttlMs = cfg.ttlMs ?? 6e4;
+    const ctx = {
+      reservationId,
+      estimate,
+      decision,
+      caps: resResult.caps,
+      expiresAtMs: resResult.expiresAtMs,
+      affectedScopes: resResult.affectedScopes,
+      scopePath: resResult.scopePath,
+      reserved: resResult.reserved,
+      balances: resResult.balances
+    };
+    const heartbeatRef = this._startHeartbeat(reservationId, ttlMs, ctx);
+    try {
+      const result = await runWithContext(ctx, () => fn(...args));
+      const methodElapsed = Math.round(performance.now() - resT2);
+      const useEstimateFallback = cfg.useEstimateIfActualNotProvided !== false;
+      const actualAmount = evaluateActual(
+        cfg.actual,
+        result,
+        estimate,
+        useEstimateFallback
+      );
+      let metrics = ctx.metrics;
+      if (!metrics) {
+        metrics = {};
+      }
+      if (metrics.latencyMs === void 0) {
+        metrics = { ...metrics, latencyMs: methodElapsed };
+      }
+      const commitBody = buildCommitBody(
+        actualAmount,
+        unit,
+        metrics,
+        ctx.commitMetadata
+      );
+      await this._handleCommit(reservationId, commitBody);
+      return result;
+    } catch (err) {
+      await this._handleRelease(reservationId, "guarded_method_failed");
+      throw err;
+    } finally {
+      if (heartbeatRef) {
+        heartbeatRef.stop();
+      }
+    }
+  }
+  async _handleCommit(reservationId, commitBody) {
+    try {
+      const response = await this._client.commitReservation(
+        reservationId,
+        commitBody
+      );
+      if (response.isSuccess) {
+        return;
+      }
+      if (response.isTransportError || response.isServerError) {
+        this._retryEngine.schedule(reservationId, commitBody);
+        return;
+      }
+      const errorResp = response.getErrorResponse();
+      const errorCode = errorResp?.error;
+      if (errorCode === "RESERVATION_FINALIZED" || errorCode === "RESERVATION_EXPIRED") {
+        return;
+      }
+      if (errorCode === "IDEMPOTENCY_MISMATCH") {
+        return;
+      }
+      if (response.isClientError) {
+        await this._handleRelease(
+          reservationId,
+          `commit_rejected_${errorCode}`
+        );
+        return;
+      }
+    } catch {
+      this._retryEngine.schedule(reservationId, commitBody);
+    }
+  }
+  async _handleRelease(reservationId, reason) {
+    try {
+      const body = buildReleaseBody(reason);
+      await this._client.releaseReservation(reservationId, body);
+    } catch {
+    }
+  }
+  _startHeartbeat(reservationId, ttlMs, ctx) {
+    if (ttlMs <= 0) return void 0;
+    const intervalMs = Math.max(ttlMs / 2, 1e3);
+    let stopped = false;
+    let currentTimer;
+    const tick = () => {
+      if (stopped) return;
+      currentTimer = setTimeout(() => {
+        if (stopped) return;
+        const body = buildExtendBody(ttlMs);
+        void this._client.extendReservation(reservationId, body).then((response) => {
+          if (response.isSuccess) {
+            const newExpires = response.getBodyAttribute("expires_at_ms");
+            if (typeof newExpires === "number") {
+              ctx.expiresAtMs = newExpires;
+            }
+          }
+        }).catch(() => {
+        }).finally(() => {
+          tick();
+        });
+      }, intervalMs);
+    };
+    tick();
+    return {
+      stop: () => {
+        stopped = true;
+        clearTimeout(currentTimer);
+      }
+    };
+  }
+};
+
+// src/retry.ts
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+var CommitRetryEngine = class {
+  _enabled;
+  _maxAttempts;
+  _initialDelay;
+  _multiplier;
+  _maxDelay;
+  _client;
+  constructor(config) {
+    this._enabled = config.retryEnabled;
+    this._maxAttempts = config.retryMaxAttempts;
+    this._initialDelay = config.retryInitialDelay;
+    this._multiplier = config.retryMultiplier;
+    this._maxDelay = config.retryMaxDelay;
+  }
+  setClient(client) {
+    this._client = client;
+  }
+  schedule(reservationId, commitBody) {
+    if (!this._enabled) {
+      return;
+    }
+    void this._retryLoop(reservationId, commitBody);
+  }
+  async _retryLoop(reservationId, commitBody) {
+    for (let attempt = 0; attempt < this._maxAttempts; attempt++) {
+      const backoff = Math.min(
+        this._initialDelay * this._multiplier ** attempt,
+        this._maxDelay
+      );
+      await delay(backoff);
+      try {
+        if (!this._client) {
+          return;
+        }
+        const response = await this._client.commitReservation(
+          reservationId,
+          commitBody
+        );
+        if (response.isSuccess) {
+          return;
+        }
+        if (response.isClientError) {
+          return;
+        }
+      } catch {
+      }
+    }
+  }
+};
+
+// src/withCycles.ts
+var _defaultClient;
+var _defaultConfig;
+function setDefaultClient(client) {
+  _defaultClient = client;
+}
+function setDefaultConfig(config) {
+  _defaultConfig = config;
+}
+function getEffectiveClient(explicitClient) {
+  if (explicitClient) return explicitClient;
+  if (_defaultClient) return _defaultClient;
+  if (_defaultConfig) {
+    _defaultClient = new CyclesClient(_defaultConfig);
+    return _defaultClient;
+  }
+  throw new Error(
+    "No Cycles client available. Either pass client in options, call setDefaultClient(), or call setDefaultConfig()."
+  );
+}
+function withCycles(options, fn) {
+  return async (...args) => {
+    const client = getEffectiveClient(options.client);
+    const config = client.config;
+    const defaultSubject = {
+      tenant: config.tenant,
+      workspace: config.workspace,
+      app: config.app,
+      workflow: config.workflow,
+      agent: config.agent,
+      toolset: config.toolset
+    };
+    const retryEngine = new CommitRetryEngine(config);
+    const lifecycle = new AsyncCyclesLifecycle(
+      client,
+      retryEngine,
+      defaultSubject
+    );
+    return lifecycle.execute(
+      fn,
+      args,
+      options
+    );
+  };
+}
+
+// src/streaming.ts
+import { randomUUID as randomUUID2 } from "crypto";
+
+// src/models.ts
+var Unit = /* @__PURE__ */ ((Unit2) => {
+  Unit2["USD_MICROCENTS"] = "USD_MICROCENTS";
+  Unit2["TOKENS"] = "TOKENS";
+  Unit2["CREDITS"] = "CREDITS";
+  Unit2["RISK_POINTS"] = "RISK_POINTS";
+  return Unit2;
+})(Unit || {});
+var CommitOveragePolicy = /* @__PURE__ */ ((CommitOveragePolicy2) => {
+  CommitOveragePolicy2["REJECT"] = "REJECT";
+  CommitOveragePolicy2["ALLOW_IF_AVAILABLE"] = "ALLOW_IF_AVAILABLE";
+  CommitOveragePolicy2["ALLOW_WITH_OVERDRAFT"] = "ALLOW_WITH_OVERDRAFT";
+  return CommitOveragePolicy2;
+})(CommitOveragePolicy || {});
+var Decision = /* @__PURE__ */ ((Decision2) => {
+  Decision2["ALLOW"] = "ALLOW";
+  Decision2["ALLOW_WITH_CAPS"] = "ALLOW_WITH_CAPS";
+  Decision2["DENY"] = "DENY";
+  return Decision2;
+})(Decision || {});
+var ReservationStatus = /* @__PURE__ */ ((ReservationStatus2) => {
+  ReservationStatus2["ACTIVE"] = "ACTIVE";
+  ReservationStatus2["COMMITTED"] = "COMMITTED";
+  ReservationStatus2["RELEASED"] = "RELEASED";
+  ReservationStatus2["EXPIRED"] = "EXPIRED";
+  return ReservationStatus2;
+})(ReservationStatus || {});
+var CommitStatus = /* @__PURE__ */ ((CommitStatus2) => {
+  CommitStatus2["COMMITTED"] = "COMMITTED";
+  return CommitStatus2;
+})(CommitStatus || {});
+var ReleaseStatus = /* @__PURE__ */ ((ReleaseStatus2) => {
+  ReleaseStatus2["RELEASED"] = "RELEASED";
+  return ReleaseStatus2;
+})(ReleaseStatus || {});
+var ExtendStatus = /* @__PURE__ */ ((ExtendStatus2) => {
+  ExtendStatus2["ACTIVE"] = "ACTIVE";
+  return ExtendStatus2;
+})(ExtendStatus || {});
+var EventStatus = /* @__PURE__ */ ((EventStatus2) => {
+  EventStatus2["APPLIED"] = "APPLIED";
+  return EventStatus2;
+})(EventStatus || {});
+var ErrorCode = /* @__PURE__ */ ((ErrorCode2) => {
+  ErrorCode2["INVALID_REQUEST"] = "INVALID_REQUEST";
+  ErrorCode2["UNAUTHORIZED"] = "UNAUTHORIZED";
+  ErrorCode2["FORBIDDEN"] = "FORBIDDEN";
+  ErrorCode2["NOT_FOUND"] = "NOT_FOUND";
+  ErrorCode2["BUDGET_EXCEEDED"] = "BUDGET_EXCEEDED";
+  ErrorCode2["RESERVATION_EXPIRED"] = "RESERVATION_EXPIRED";
+  ErrorCode2["RESERVATION_FINALIZED"] = "RESERVATION_FINALIZED";
+  ErrorCode2["IDEMPOTENCY_MISMATCH"] = "IDEMPOTENCY_MISMATCH";
+  ErrorCode2["UNIT_MISMATCH"] = "UNIT_MISMATCH";
+  ErrorCode2["OVERDRAFT_LIMIT_EXCEEDED"] = "OVERDRAFT_LIMIT_EXCEEDED";
+  ErrorCode2["DEBT_OUTSTANDING"] = "DEBT_OUTSTANDING";
+  ErrorCode2["INTERNAL_ERROR"] = "INTERNAL_ERROR";
+  ErrorCode2["UNKNOWN"] = "UNKNOWN";
+  return ErrorCode2;
+})(ErrorCode || {});
+function isAllowed(decision) {
+  return decision === "ALLOW" /* ALLOW */ || decision === "ALLOW_WITH_CAPS" /* ALLOW_WITH_CAPS */;
+}
+function isDenied(decision) {
+  return decision === "DENY" /* DENY */;
+}
+function isRetryableErrorCode(code) {
+  return code === "INTERNAL_ERROR" /* INTERNAL_ERROR */ || code === "UNKNOWN" /* UNKNOWN */;
+}
+function errorCodeFromString(value) {
+  if (value === void 0) return void 0;
+  if (Object.values(ErrorCode).includes(value)) {
+    return value;
+  }
+  return "UNKNOWN" /* UNKNOWN */;
+}
+function isToolAllowed(caps, tool) {
+  if (caps.toolAllowlist && caps.toolAllowlist.length > 0) {
+    return caps.toolAllowlist.includes(tool);
+  }
+  if (caps.toolDenylist && caps.toolDenylist.length > 0) {
+    return !caps.toolDenylist.includes(tool);
+  }
+  return true;
+}
+function isMetricsEmpty2(metrics) {
+  return metrics.tokensInput === void 0 && metrics.tokensOutput === void 0 && metrics.latencyMs === void 0 && metrics.modelVersion === void 0 && !metrics.custom;
+}
+
+// src/streaming.ts
+async function reserveForStream(options) {
+  const {
+    client,
+    estimate,
+    unit = "USD_MICROCENTS",
+    actionKind = "unknown",
+    actionName = "unknown",
+    actionTags,
+    ttlMs = 6e4,
+    gracePeriodMs,
+    overagePolicy = "REJECT",
+    dimensions
+  } = options;
+  validateNonNegative(estimate, "estimate");
+  validateTtlMs(ttlMs);
+  validateGracePeriodMs(gracePeriodMs);
+  const configDefaults = client.config;
+  const subject = {};
+  for (const field of ["tenant", "workspace", "app", "workflow", "agent", "toolset"]) {
+    const val = options[field] ?? configDefaults[field];
+    if (val) {
+      subject[field] = val;
+    }
+  }
+  if (dimensions) {
+    subject.dimensions = dimensions;
+  }
+  validateSubject(subject);
+  const action = { kind: actionKind, name: actionName };
+  if (actionTags) {
+    action.tags = actionTags;
+  }
+  const body = {
+    idempotency_key: randomUUID2(),
+    subject,
+    action,
+    estimate: { unit, amount: estimate },
+    ttl_ms: ttlMs,
+    overage_policy: overagePolicy
+  };
+  if (gracePeriodMs !== void 0) {
+    body.grace_period_ms = gracePeriodMs;
+  }
+  const response = await client.createReservation(body);
+  if (!response.isSuccess) {
+    throw buildProtocolException("Failed to create reservation", response);
+  }
+  const parsed = reservationCreateResponseFromWire(
+    response.body
+  );
+  if (parsed.decision === "DENY") {
+    throw buildProtocolException("Reservation denied", response);
+  }
+  const reservationId = parsed.reservationId;
+  if (!reservationId) {
+    throw new CyclesProtocolError(
+      "Reservation successful but reservation_id missing",
+      { status: response.status }
+    );
+  }
+  let heartbeatStopped = false;
+  let finalized = false;
+  let currentTimer;
+  const stopHeartbeat = () => {
+    if (!heartbeatStopped) {
+      heartbeatStopped = true;
+      clearTimeout(currentTimer);
+    }
+  };
+  const startHeartbeat = () => {
+    if (ttlMs <= 0) return;
+    const intervalMs = Math.max(ttlMs / 2, 1e3);
+    const tick = () => {
+      if (heartbeatStopped) return;
+      currentTimer = setTimeout(() => {
+        if (heartbeatStopped) return;
+        validateExtendByMs(ttlMs);
+        const extendBody = { idempotency_key: randomUUID2(), extend_by_ms: ttlMs };
+        void client.extendReservation(reservationId, extendBody).catch(() => {
+        }).finally(() => {
+          tick();
+        });
+      }, intervalMs);
+    };
+    tick();
+  };
+  startHeartbeat();
+  return {
+    reservationId,
+    decision: parsed.decision,
+    caps: parsed.caps,
+    get finalized() {
+      return finalized;
+    },
+    async commit(actual, metrics, metadata) {
+      if (finalized) {
+        throw new CyclesError("StreamReservation already finalized");
+      }
+      finalized = true;
+      stopHeartbeat();
+      const commitBody = {
+        idempotency_key: randomUUID2(),
+        actual: { unit, amount: actual }
+      };
+      if (metrics && !isMetricsEmpty2(metrics)) {
+        commitBody.metrics = metricsToWire(metrics);
+      }
+      if (metadata) {
+        commitBody.metadata = metadata;
+      }
+      await client.commitReservation(reservationId, commitBody);
+    },
+    async release(reason) {
+      if (finalized) return;
+      finalized = true;
+      stopHeartbeat();
+      try {
+        const releaseBody = { idempotency_key: randomUUID2(), reason: reason ?? "stream_aborted" };
+        await client.releaseReservation(reservationId, releaseBody);
+      } catch {
+      }
+    },
+    dispose() {
+      if (finalized) return;
+      finalized = true;
+      stopHeartbeat();
+    }
+  };
+}
+export {
+  BudgetExceededError,
+  CommitOveragePolicy,
+  CommitStatus,
+  CyclesClient,
+  CyclesConfig,
+  CyclesError,
+  CyclesProtocolError,
+  CyclesResponse,
+  CyclesTransportError,
+  DebtOutstandingError,
+  Decision,
+  ErrorCode,
+  EventStatus,
+  ExtendStatus,
+  OverdraftLimitExceededError,
+  ReleaseStatus,
+  ReservationExpiredError,
+  ReservationFinalizedError,
+  ReservationStatus,
+  Unit,
+  balanceResponseFromWire,
+  capsFromWire,
+  commitRequestToWire,
+  commitResponseFromWire,
+  decisionRequestToWire,
+  decisionResponseFromWire,
+  errorCodeFromString,
+  errorResponseFromWire,
+  eventCreateRequestToWire,
+  eventCreateResponseFromWire,
+  getCyclesContext,
+  isAllowed,
+  isDenied,
+  isMetricsEmpty2 as isMetricsEmpty,
+  isRetryableErrorCode,
+  isToolAllowed,
+  metricsToWire,
+  releaseRequestToWire,
+  releaseResponseFromWire,
+  reservationCreateRequestToWire,
+  reservationCreateResponseFromWire,
+  reservationDetailFromWire,
+  reservationExtendRequestToWire,
+  reservationExtendResponseFromWire,
+  reservationListResponseFromWire,
+  reservationSummaryFromWire,
+  reserveForStream,
+  setDefaultClient,
+  setDefaultConfig,
+  withCycles
+};