runcycles 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,551 @@
+/** Configuration for the Cycles client. */
+declare class CyclesConfig {
+    readonly baseUrl: string;
+    readonly apiKey: string;
+    readonly tenant?: string;
+    readonly workspace?: string;
+    readonly app?: string;
+    readonly workflow?: string;
+    readonly agent?: string;
+    readonly toolset?: string;
+    readonly connectTimeout: number;
+    readonly readTimeout: number;
+    readonly retryEnabled: boolean;
+    readonly retryMaxAttempts: number;
+    readonly retryInitialDelay: number;
+    readonly retryMultiplier: number;
+    readonly retryMaxDelay: number;
+    constructor(options: {
+        baseUrl: string;
+        apiKey: string;
+        tenant?: string;
+        workspace?: string;
+        app?: string;
+        workflow?: string;
+        agent?: string;
+        toolset?: string;
+        connectTimeout?: number;
+        readTimeout?: number;
+        retryEnabled?: boolean;
+        retryMaxAttempts?: number;
+        retryInitialDelay?: number;
+        retryMultiplier?: number;
+        retryMaxDelay?: number;
+    });
+    static fromEnv(prefix?: string): CyclesConfig;
+}
+
+/** Enums, interfaces, and helper functions for the Cycles protocol. */
+declare enum Unit {
+    USD_MICROCENTS = "USD_MICROCENTS",
+    TOKENS = "TOKENS",
+    CREDITS = "CREDITS",
+    RISK_POINTS = "RISK_POINTS"
+}
+declare enum CommitOveragePolicy {
+    REJECT = "REJECT",
+    ALLOW_IF_AVAILABLE = "ALLOW_IF_AVAILABLE",
+    ALLOW_WITH_OVERDRAFT = "ALLOW_WITH_OVERDRAFT"
+}
+declare enum Decision {
+    ALLOW = "ALLOW",
+    ALLOW_WITH_CAPS = "ALLOW_WITH_CAPS",
+    DENY = "DENY"
+}
+declare enum ReservationStatus {
+    ACTIVE = "ACTIVE",
+    COMMITTED = "COMMITTED",
+    RELEASED = "RELEASED",
+    EXPIRED = "EXPIRED"
+}
+declare enum CommitStatus {
+    COMMITTED = "COMMITTED"
+}
+declare enum ReleaseStatus {
+    RELEASED = "RELEASED"
+}
+declare enum ExtendStatus {
+    ACTIVE = "ACTIVE"
+}
+declare enum EventStatus {
+    APPLIED = "APPLIED"
+}
+declare enum ErrorCode {
+    INVALID_REQUEST = "INVALID_REQUEST",
+    UNAUTHORIZED = "UNAUTHORIZED",
+    FORBIDDEN = "FORBIDDEN",
+    NOT_FOUND = "NOT_FOUND",
+    BUDGET_EXCEEDED = "BUDGET_EXCEEDED",
+    RESERVATION_EXPIRED = "RESERVATION_EXPIRED",
+    RESERVATION_FINALIZED = "RESERVATION_FINALIZED",
+    IDEMPOTENCY_MISMATCH = "IDEMPOTENCY_MISMATCH",
+    UNIT_MISMATCH = "UNIT_MISMATCH",
+    OVERDRAFT_LIMIT_EXCEEDED = "OVERDRAFT_LIMIT_EXCEEDED",
+    DEBT_OUTSTANDING = "DEBT_OUTSTANDING",
+    INTERNAL_ERROR = "INTERNAL_ERROR",
+    UNKNOWN = "UNKNOWN"
+}
+interface Amount {
+    unit: Unit | string;
+    amount: number;
+}
+interface SignedAmount {
+    unit: Unit | string;
+    amount: number;
+}
+interface Subject {
+    tenant?: string;
+    workspace?: string;
+    app?: string;
+    workflow?: string;
+    agent?: string;
+    toolset?: string;
+    dimensions?: Record<string, string>;
+}
+interface Action {
+    kind: string;
+    name: string;
+    tags?: string[];
+}
+interface Caps {
+    maxTokens?: number;
+    maxStepsRemaining?: number;
+    toolAllowlist?: string[];
+    toolDenylist?: string[];
+    cooldownMs?: number;
+}
+interface CyclesMetrics {
+    tokensInput?: number;
+    tokensOutput?: number;
+    latencyMs?: number;
+    modelVersion?: string;
+    custom?: Record<string, unknown>;
+}
+interface Balance {
+    scope: string;
+    scopePath: string;
+    remaining: SignedAmount;
+    reserved?: Amount;
+    spent?: Amount;
+    allocated?: Amount;
+    debt?: Amount;
+    overdraftLimit?: Amount;
+    isOverLimit?: boolean;
+}
+interface ReservationCreateRequest {
+    idempotencyKey: string;
+    subject: Subject;
+    action: Action;
+    estimate: Amount;
+    ttlMs?: number;
+    gracePeriodMs?: number;
+    overagePolicy?: CommitOveragePolicy | string;
+    dryRun?: boolean;
+    metadata?: Record<string, unknown>;
+}
+interface CommitRequest {
+    idempotencyKey: string;
+    actual: Amount;
+    metrics?: CyclesMetrics;
+    metadata?: Record<string, unknown>;
+}
+interface ReleaseRequest {
+    idempotencyKey: string;
+    reason?: string;
+}
+interface ReservationExtendRequest {
+    idempotencyKey: string;
+    extendByMs: number;
+    metadata?: Record<string, unknown>;
+}
+interface DecisionRequest {
+    idempotencyKey: string;
+    subject: Subject;
+    action: Action;
+    estimate: Amount;
+    metadata?: Record<string, unknown>;
+}
+interface EventCreateRequest {
+    idempotencyKey: string;
+    subject: Subject;
+    action: Action;
+    actual: Amount;
+    overagePolicy?: CommitOveragePolicy | string;
+    metrics?: CyclesMetrics;
+    clientTimeMs?: number;
+    metadata?: Record<string, unknown>;
+}
+interface ReservationCreateResponse {
+    decision: Decision;
+    reservationId?: string;
+    affectedScopes: string[];
+    expiresAtMs?: number;
+    scopePath?: string;
+    reserved?: Amount;
+    caps?: Caps;
+    reasonCode?: string;
+    retryAfterMs?: number;
+    balances?: Balance[];
+}
+interface CommitResponse {
+    status: CommitStatus;
+    charged: Amount;
+    released?: Amount;
+    balances?: Balance[];
+}
+interface ReleaseResponse {
+    status: ReleaseStatus;
+    released: Amount;
+    balances?: Balance[];
+}
+interface ReservationExtendResponse {
+    status: ExtendStatus;
+    expiresAtMs: number;
+    balances?: Balance[];
+}
+interface DecisionResponse {
+    decision: Decision;
+    caps?: Caps;
+    reasonCode?: string;
+    retryAfterMs?: number;
+    affectedScopes?: string[];
+}
+interface EventCreateResponse {
+    status: EventStatus;
+    eventId: string;
+    balances?: Balance[];
+}
+interface DryRunResult {
+    decision: Decision;
+    caps?: Caps;
+    affectedScopes?: string[];
+    scopePath?: string;
+    reserved?: Amount;
+    balances?: Balance[];
+    reasonCode?: string;
+    retryAfterMs?: number;
+}
+interface ErrorResponse {
+    error: string;
+    message: string;
+    requestId: string;
+    details?: Record<string, unknown>;
+}
+interface ReservationDetail {
+    reservationId: string;
+    status: ReservationStatus;
+    subject: Subject;
+    action: Action;
+    reserved: Amount;
+    createdAtMs: number;
+    expiresAtMs: number;
+    scopePath: string;
+    affectedScopes: string[];
+    idempotencyKey?: string;
+    committed?: Amount;
+    finalizedAtMs?: number;
+    metadata?: Record<string, unknown>;
+}
+interface ReservationSummary {
+    reservationId: string;
+    status: ReservationStatus;
+    subject: Subject;
+    action: Action;
+    reserved: Amount;
+    createdAtMs: number;
+    expiresAtMs: number;
+    scopePath: string;
+    affectedScopes: string[];
+    idempotencyKey?: string;
+}
+interface ReservationListResponse {
+    reservations: ReservationSummary[];
+    hasMore?: boolean;
+    nextCursor?: string;
+}
+interface BalanceResponse {
+    balances: Balance[];
+    hasMore?: boolean;
+    nextCursor?: string;
+}
+declare function isAllowed(decision: Decision): boolean;
+declare function isDenied(decision: Decision): boolean;
+declare function isRetryableErrorCode(code: ErrorCode): boolean;
+declare function errorCodeFromString(value: string | undefined): ErrorCode | undefined;
+declare function isToolAllowed(caps: Caps, tool: string): boolean;
+declare function isMetricsEmpty(metrics: CyclesMetrics): boolean;
+
+/** Uniform response wrapper for all Cycles API calls. */
+
+declare class CyclesResponse {
+    readonly status: number;
+    readonly body: Record<string, unknown> | undefined;
+    readonly errorMessage: string | undefined;
+    readonly headers: Record<string, string>;
+    private readonly _isTransportError;
+    readonly transportError: Error | undefined;
+    private constructor();
+    static success(status: number, body: Record<string, unknown>, headers?: Record<string, string>): CyclesResponse;
+    static httpError(status: number, errorMessage: string, body?: Record<string, unknown>, headers?: Record<string, string>): CyclesResponse;
+    static transportError(err: Error): CyclesResponse;
+    get requestId(): string | undefined;
+    get rateLimitRemaining(): number | undefined;
+    get rateLimitReset(): number | undefined;
+    get cyclesTenant(): string | undefined;
+    get isSuccess(): boolean;
+    get isClientError(): boolean;
+    get isServerError(): boolean;
+    get isTransportError(): boolean;
+    getBodyAttribute(key: string): unknown;
+    getErrorResponse(): ErrorResponse | undefined;
+}
+
+/**
+ * Async HTTP client for the Cycles API.
+ *
+ * The client is transport-oriented and runtime-agnostic: it sends and receives
+ * wire-format (snake_case) JSON bodies without any automatic key conversion.
+ * Callers are responsible for building wire-format request bodies; the response
+ * body is returned in wire format for explicit mapping by the caller.
+ *
+ * Timeout note: Node's built-in fetch does not distinguish connection timeout
+ * from read timeout. The config's connectTimeout and readTimeout are summed
+ * into a single AbortSignal.timeout() value that caps total request duration.
+ * For stricter timeout control, consider using a custom HTTP client.
+ */
+
+declare class CyclesClient {
+    private readonly _config;
+    constructor(config: CyclesConfig);
+    get config(): CyclesConfig;
+    createReservation(request: Record<string, unknown>): Promise<CyclesResponse>;
+    commitReservation(reservationId: string, request: Record<string, unknown>): Promise<CyclesResponse>;
+    releaseReservation(reservationId: string, request: Record<string, unknown>): Promise<CyclesResponse>;
+    extendReservation(reservationId: string, request: Record<string, unknown>): Promise<CyclesResponse>;
+    decide(request: Record<string, unknown>): Promise<CyclesResponse>;
+    listReservations(params?: Record<string, string>): Promise<CyclesResponse>;
+    getReservation(reservationId: string): Promise<CyclesResponse>;
+    getBalances(params: Record<string, string>): Promise<CyclesResponse>;
+    createEvent(request: Record<string, unknown>): Promise<CyclesResponse>;
+    private _post;
+    private _get;
+    private _handleResponse;
+}
+
+/** Lifecycle orchestration: reserve -> execute -> commit/release. */
+
+interface WithCyclesConfig {
+    estimate: number | ((...args: unknown[]) => number);
+    actual?: number | ((result: unknown) => number);
+    actionKind?: string;
+    actionName?: string;
+    actionTags?: string[];
+    unit?: string;
+    ttlMs?: number;
+    gracePeriodMs?: number;
+    overagePolicy?: string;
+    dryRun?: boolean;
+    tenant?: string;
+    workspace?: string;
+    app?: string;
+    workflow?: string;
+    agent?: string;
+    toolset?: string;
+    dimensions?: Record<string, string>;
+    useEstimateIfActualNotProvided?: boolean;
+}
+
+/** The withCycles higher-order function for budget-guarded function calls. */
+
+declare function setDefaultClient(client: CyclesClient): void;
+declare function setDefaultConfig(config: CyclesConfig): void;
+declare function withCycles<TArgs extends unknown[], TResult>(options: WithCyclesConfig & {
+    client?: CyclesClient;
+}, fn: (...args: TArgs) => Promise<TResult>): (...args: TArgs) => Promise<TResult>;
+
+/**
+ * First-class streaming adapter for Cycles budget governance.
+ *
+ * Unlike `withCycles` (which wraps a Promise-returning function and commits
+ * immediately after the function resolves), `reserveForStream` returns a
+ * handle that lets the caller control when to commit or release. This is
+ * essential for LLM streaming where the function returns a stream object
+ * immediately but actual usage is only known after the stream finishes.
+ *
+ * The handle owns its own finalization: calling `commit()` or `release()`
+ * automatically stops the heartbeat. There is no need for a `finally`
+ * block around the stream — the heartbeat lives until a terminal
+ * operation (commit/release) is reached.
+ *
+ * RACE SAFETY: In real streaming code, multiple terminal paths can fire
+ * concurrently (onFinish, error handler, abort signal, client disconnect).
+ * The handle is once-only: the first terminal call (commit/release/dispose)
+ * wins, and subsequent calls are either no-ops (release, dispose) or throw
+ * (commit). Check `handle.finalized` to inspect state.
+ *
+ * Typical lifecycle:
+ *   1. `reserveForStream(...)` — creates reservation + starts heartbeat
+ *   2. Start streaming (e.g. `streamText(...)`)
+ *   3. On stream finish → `handle.commit(actualCost, metrics)` (stops heartbeat)
+ *   4. On stream error/abort → `handle.release("aborted")` (stops heartbeat)
+ *   5. If stream startup fails before streaming begins → `handle.dispose()`
+ */
+
+interface StreamReservationOptions {
+    client: CyclesClient;
+    estimate: number;
+    unit?: string;
+    actionKind?: string;
+    actionName?: string;
+    actionTags?: string[];
+    ttlMs?: number;
+    gracePeriodMs?: number;
+    overagePolicy?: string;
+    tenant?: string;
+    workspace?: string;
+    app?: string;
+    workflow?: string;
+    agent?: string;
+    toolset?: string;
+    dimensions?: Record<string, string>;
+}
+interface StreamReservation {
+    /** The reservation ID from the server. */
+    readonly reservationId: string;
+    /** The budget decision (ALLOW or ALLOW_WITH_CAPS). */
+    readonly decision: Decision;
+    /** Caps imposed by the budget, if any. */
+    readonly caps: Caps | undefined;
+    /** True after commit(), release(), or dispose() has been called. */
+    readonly finalized: boolean;
+    /**
+     * Commit actual usage after the stream completes successfully.
+     * Automatically stops the heartbeat. Call from `onFinish` or equivalent.
+     * Throws `CyclesError` if the handle is already finalized.
+     */
+    commit(actual: number, metrics?: CyclesMetrics, metadata?: Record<string, unknown>): Promise<void>;
+    /**
+     * Release the reservation on error or abort.
+     * Automatically stops the heartbeat. Best-effort — errors are swallowed.
+     * No-op if the handle is already finalized.
+     */
+    release(reason?: string): Promise<void>;
+    /**
+     * Stop the heartbeat timer without committing or releasing.
+     * Use only for stream startup failures where the stream was never started.
+     * For normal finalization, use `commit()` or `release()` instead.
+     * No-op if the handle is already finalized.
+     */
+    dispose(): void;
+}
+/**
+ * Reserve budget for a streaming operation and return a handle to
+ * commit or release when the stream completes.
+ *
+ * Throws `BudgetExceededError` (or other protocol errors) if the
+ * reservation is denied.
+ */
+declare function reserveForStream(options: StreamReservationOptions): Promise<StreamReservation>;
+
+/** AsyncLocalStorage-based context holder for active Cycles reservations. */
+
+interface CyclesContext {
+    readonly reservationId: string;
+    readonly estimate: number;
+    readonly decision: Decision;
+    readonly caps?: Caps;
+    expiresAtMs?: number;
+    readonly affectedScopes?: string[];
+    readonly scopePath?: string;
+    readonly reserved?: Amount;
+    readonly balances?: Balance[];
+    metrics?: CyclesMetrics;
+    commitMetadata?: Record<string, unknown>;
+}
+declare function getCyclesContext(): CyclesContext | undefined;
+
+/** Exception hierarchy for the Cycles client. */
+declare class CyclesError extends Error {
+    constructor(message: string);
+}
+declare class CyclesProtocolError extends CyclesError {
+    readonly status: number;
+    readonly errorCode: string | undefined;
+    readonly reasonCode: string | undefined;
+    readonly retryAfterMs: number | undefined;
+    readonly requestId: string | undefined;
+    readonly details: Record<string, unknown> | undefined;
+    constructor(message: string, options?: {
+        status?: number;
+        errorCode?: string;
+        reasonCode?: string;
+        retryAfterMs?: number;
+        requestId?: string;
+        details?: Record<string, unknown>;
+    });
+    isBudgetExceeded(): boolean;
+    isOverdraftLimitExceeded(): boolean;
+    isDebtOutstanding(): boolean;
+    isReservationExpired(): boolean;
+    isReservationFinalized(): boolean;
+    isIdempotencyMismatch(): boolean;
+    isUnitMismatch(): boolean;
+    isRetryable(): boolean;
+}
+declare class BudgetExceededError extends CyclesProtocolError {
+    constructor(message: string, options?: ConstructorParameters<typeof CyclesProtocolError>[1]);
+}
+declare class OverdraftLimitExceededError extends CyclesProtocolError {
+    constructor(message: string, options?: ConstructorParameters<typeof CyclesProtocolError>[1]);
+}
+declare class DebtOutstandingError extends CyclesProtocolError {
+    constructor(message: string, options?: ConstructorParameters<typeof CyclesProtocolError>[1]);
+}
+declare class ReservationExpiredError extends CyclesProtocolError {
+    constructor(message: string, options?: ConstructorParameters<typeof CyclesProtocolError>[1]);
+}
+declare class ReservationFinalizedError extends CyclesProtocolError {
+    constructor(message: string, options?: ConstructorParameters<typeof CyclesProtocolError>[1]);
+}
+declare class CyclesTransportError extends CyclesError {
+    readonly cause: Error | undefined;
+    constructor(message: string, options?: {
+        cause?: Error;
+    });
+}
+
+/**
+ * Explicit request/response mappers between camelCase TypeScript interfaces
+ * and snake_case wire format.
+ *
+ * These are intentionally verbose — each field is mapped individually so that
+ * protocol drift is immediately visible, special cases are handled explicitly,
+ * and the wire contract is auditable.
+ */
+
+declare function metricsToWire(metrics: CyclesMetrics): Record<string, unknown>;
+declare function capsFromWire(wire: Record<string, unknown> | undefined): Caps | undefined;
+declare function reservationCreateResponseFromWire(wire: Record<string, unknown>): ReservationCreateResponse;
+declare function commitResponseFromWire(wire: Record<string, unknown>): CommitResponse;
+declare function releaseResponseFromWire(wire: Record<string, unknown>): ReleaseResponse;
+declare function reservationExtendResponseFromWire(wire: Record<string, unknown>): ReservationExtendResponse;
+declare function decisionResponseFromWire(wire: Record<string, unknown>): DecisionResponse;
+declare function eventCreateResponseFromWire(wire: Record<string, unknown>): EventCreateResponse;
+declare function reservationDetailFromWire(wire: Record<string, unknown>): ReservationDetail;
+declare function reservationSummaryFromWire(wire: Record<string, unknown>): ReservationSummary;
+declare function reservationListResponseFromWire(wire: Record<string, unknown>): ReservationListResponse;
+declare function balanceResponseFromWire(wire: Record<string, unknown>): BalanceResponse;
+declare function errorResponseFromWire(wire: Record<string, unknown>): {
+    error: string;
+    message: string;
+    requestId: string;
+    details?: Record<string, unknown>;
+} | undefined;
+declare function reservationCreateRequestToWire(req: ReservationCreateRequest): Record<string, unknown>;
+declare function commitRequestToWire(req: CommitRequest): Record<string, unknown>;
+declare function releaseRequestToWire(req: ReleaseRequest): Record<string, unknown>;
+declare function reservationExtendRequestToWire(req: ReservationExtendRequest): Record<string, unknown>;
+declare function decisionRequestToWire(req: DecisionRequest): Record<string, unknown>;
+declare function eventCreateRequestToWire(req: EventCreateRequest): Record<string, unknown>;
+
+export { type Action, type Amount, type Balance, type BalanceResponse, BudgetExceededError, type Caps, CommitOveragePolicy, type CommitRequest, type CommitResponse, CommitStatus, CyclesClient, CyclesConfig, type CyclesContext, CyclesError, type CyclesMetrics, CyclesProtocolError, CyclesResponse, CyclesTransportError, DebtOutstandingError, Decision, type DecisionRequest, type DecisionResponse, type DryRunResult, ErrorCode, type ErrorResponse, type EventCreateRequest, type EventCreateResponse, EventStatus, ExtendStatus, OverdraftLimitExceededError, type ReleaseRequest, type ReleaseResponse, ReleaseStatus, type ReservationCreateRequest, type ReservationCreateResponse, type ReservationDetail, ReservationExpiredError, type ReservationExtendRequest, type ReservationExtendResponse, ReservationFinalizedError, type ReservationListResponse, ReservationStatus, type ReservationSummary, type SignedAmount, type StreamReservation, type StreamReservationOptions, type Subject, Unit, type WithCyclesConfig, balanceResponseFromWire, capsFromWire, commitRequestToWire, commitResponseFromWire, decisionRequestToWire, decisionResponseFromWire, errorCodeFromString, errorResponseFromWire, eventCreateRequestToWire, eventCreateResponseFromWire, getCyclesContext, isAllowed, isDenied, isMetricsEmpty, isRetryableErrorCode, isToolAllowed, metricsToWire, releaseRequestToWire, releaseResponseFromWire, reservationCreateRequestToWire, reservationCreateResponseFromWire, reservationDetailFromWire, reservationExtendRequestToWire, reservationExtendResponseFromWire, reservationListResponseFromWire, reservationSummaryFromWire, reserveForStream, setDefaultClient, setDefaultConfig, withCycles };