runcycles 0.1.2 → 0.3.0

package/README.md

@@ -1,3 +1,9 @@
+[![npm](https://img.shields.io/npm/v/runcycles)](https://www.npmjs.com/package/runcycles)
+[![npm Downloads](https://img.shields.io/npm/dm/runcycles)](https://www.npmjs.com/package/runcycles)
+[![CI](https://github.com/runcycles/cycles-client-typescript/actions/workflows/ci.yml/badge.svg)](https://github.com/runcycles/cycles-client-typescript/actions)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
+[![Coverage](https://img.shields.io/badge/coverage-98%25-brightgreen)](https://github.com/runcycles/cycles-client-typescript/actions)
+
 # Cycles TypeScript Client
 
 TypeScript client for the [Cycles](https://runcycles.io) budget-management protocol — govern spend on AI calls, API usage, and any metered resource.
@@ -69,6 +75,24 @@ const result = await callLlm("Hello", 100);
 
 **What happens:** `withCycles` reserves budget before calling your function, runs it inside an async context (so `getCyclesContext()` works), commits the actual cost on success, or releases the reservation on failure. A background heartbeat keeps the reservation alive.
 
+### Budget lifecycle
+
+| Scenario | Outcome | Detail |
+|---|---|---|
+| Reservation denied | **Neither** | `BudgetExceededError`, `OverdraftLimitExceededError`, or `DebtOutstandingError` thrown; function never executes |
+| `dryRun: true`, any decision | **Neither** | Returns `DryRunResult` or throws; no real reservation created |
+| Function returns successfully | **Commit** | Actual amount charged; unused remainder auto-released |
+| Function throws any error | **Release** | Full reserved amount returned to budget; error re-thrown |
+| Commit fails (5xx / network) | **Retry** | Exponential backoff with configurable attempts |
+| Commit fails (non-retryable 4xx) | **Release** | Reservation released after non-retryable client error |
+| Commit gets RESERVATION_EXPIRED | **Neither** | Server already reclaimed budget on TTL expiry |
+| Commit gets RESERVATION_FINALIZED | **Neither** | Already committed or released (idempotent replay) |
+| Commit gets IDEMPOTENCY_MISMATCH | **Neither** | Previous commit already processed; no release attempted |
+
+**Streaming (`reserveForStream`):** Call `handle.commit(actual)` on success or `handle.release(reason)` on failure. If neither is called, the server reclaims the budget when the reservation TTL expires.
+
+All thrown errors from the guarded function trigger release. See [How Reserve-Commit Works](https://runcycles.io/protocol/how-reserve-commit-works-in-cycles) for the full protocol-level explanation.
+
 ### 2. Streaming adapter
 
 For LLM streaming where usage is only known after the stream finishes:
@@ -292,9 +316,9 @@ interface WithCyclesConfig {
   actual?: number | ((result) => number);    // Actual cost (static or computed from result)
   useEstimateIfActualNotProvided?: boolean;  // Default: true — use estimate as actual
 
-  // Action identification
-  actionKind?: string;   // e.g. "llm.completion" (default: "unknown")
-  actionName?: string;   // e.g. "gpt-4" (default: "unknown")
+  // Action identification (static or computed from args)
+  actionKind?: string | ((...args) => string | undefined);  // e.g. "llm.completion" (default: "unknown")
+  actionName?: string | ((...args) => string | undefined);  // e.g. "gpt-4" (default: "unknown")
   actionTags?: string[]; // Optional tags for categorization
 
   // Budget unit
@@ -303,16 +327,16 @@ interface WithCyclesConfig {
   // Reservation settings
   ttlMs?: number;          // Time-to-live in ms (default: 60000, range: 1000–86400000)
   gracePeriodMs?: number;  // Grace period in ms (range: 0–60000)
-  overagePolicy?: string;  // "REJECT" (default), "ALLOW_IF_AVAILABLE", "ALLOW_WITH_OVERDRAFT"
+  overagePolicy?: string;  // "ALLOW_IF_AVAILABLE" (default), "REJECT", "ALLOW_WITH_OVERDRAFT"
   dryRun?: boolean;        // Shadow mode — evaluates budget without executing
 
-  // Subject fields (override config defaults)
-  tenant?: string;
-  workspace?: string;
-  app?: string;
-  workflow?: string;
-  agent?: string;
-  toolset?: string;
+  // Subject fields (override config defaults; static or computed from args)
+  tenant?: string | ((...args) => string | undefined);
+  workspace?: string | ((...args) => string | undefined);
+  app?: string | ((...args) => string | undefined);
+  workflow?: string | ((...args) => string | undefined);
+  agent?: string | ((...args) => string | undefined);
+  toolset?: string | ((...args) => string | undefined);
   dimensions?: Record<string, string>;  // Custom key-value dimensions
 
   // Client
@@ -320,6 +344,28 @@ interface WithCyclesConfig {
 }
 ```
 
+A callable returning `undefined` falls through to the client-config default for subject fields, or to `"unknown"` for `actionKind` / `actionName` — same fallback semantics as a missing static. Callables run before the reservation is created; if one throws, the reservation is never attempted and the error propagates to the caller.
+
+### Dynamic subject and action fields
+
+Derive the subject scope or action identity from per-call arguments:
+
+```typescript
+const runRequest = withCycles(
+  {
+    estimate: (req, workspaceId) => req.tokens * 10,
+    workspace: (_req, workspaceId) => workspaceId,
+    actionKind: "llm.completion",
+    actionName: (req) => req.model,
+    client,
+  },
+  async (req: { tokens: number; model: string }, workspaceId: string) => {
+    // ... the reservation routes to this workspaceId ...
+    return callLLM(req);
+  },
+);
+```
+
 ## Context Access
 
 Inside a `withCycles`-guarded function, access the active reservation via `getCyclesContext()`:
@@ -795,6 +841,29 @@ ErrorCode.INTERNAL_ERROR
 ErrorCode.UNKNOWN
 ```
 
+## Nested `withCycles` Calls
+
+Calling a `withCycles`-wrapped function from inside another `withCycles`-wrapped function is allowed — it will not throw an error. However, each wrapper creates an **independent reservation** that deducts budget separately:
+
+```typescript
+const inner = withCycles({ estimate: 100, actionName: "inner" }, async () => "done");
+const outer = withCycles({ estimate: 500, actionName: "outer" }, async () => {
+  return await inner(); // creates a SECOND reservation — 600 total deducted, not 500
+});
+```
+
+This means nested guards **double-count budget**. The outer reservation already covers the full estimated cost of the operation, so an inner reservation deducts additional budget from the same pool.
+
+**Recommended pattern:** Place `withCycles` at the outermost entry point only. Inner functions should be plain async functions without their own guard:
+
+```typescript
+const inner = async () => "done"; // no withCycles — called within a guarded operation
+
+const outer = withCycles({ estimate: 500, actionName: "outer" }, async () => {
+  return await inner(); // single reservation — 500 total
+});
+```
+
 ## Examples
 
 See the [`examples/`](./examples/) directory:
@@ -824,6 +893,13 @@ See the [`examples/`](./examples/) directory:
 - **Dual ESM/CJS**: Works with both module systems
 - **Input validation**: Client-side validation of TTL, amounts, subject fields, and more
 
+## Documentation
+
+- [Cycles Documentation](https://runcycles.io) — full docs site
+- [TypeScript Quickstart](https://runcycles.io/quickstart/getting-started-with-the-typescript-client) — getting started guide
+- [TypeScript Client Configuration Reference](https://runcycles.io/configuration/typescript-client-configuration-reference) — all configuration options
+- [Error Handling Patterns in TypeScript](https://runcycles.io/how-to/error-handling-patterns-in-typescript) — handling budget errors
+
 ## License
 
 Apache-2.0

package/dist/index.cjs

@@ -835,12 +835,15 @@ var ErrorCode = /* @__PURE__ */ ((ErrorCode2) => {
   ErrorCode2["FORBIDDEN"] = "FORBIDDEN";
   ErrorCode2["NOT_FOUND"] = "NOT_FOUND";
   ErrorCode2["BUDGET_EXCEEDED"] = "BUDGET_EXCEEDED";
+  ErrorCode2["BUDGET_FROZEN"] = "BUDGET_FROZEN";
+  ErrorCode2["BUDGET_CLOSED"] = "BUDGET_CLOSED";
   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["MAX_EXTENSIONS_EXCEEDED"] = "MAX_EXTENSIONS_EXCEEDED";
   ErrorCode2["INTERNAL_ERROR"] = "INTERNAL_ERROR";
   ErrorCode2["UNKNOWN"] = "UNKNOWN";
   return ErrorCode2;
@@ -926,7 +929,13 @@ function evaluateActual(expr, result, estimate, useEstimateFallback) {
     "actual expression is required when useEstimateIfActualNotProvided is false"
   );
 }
-function buildReservationBody(cfg, estimate, defaultSubject) {
+function evaluateStringField(expr, args) {
+  if (typeof expr === "function") {
+    return expr(...args);
+  }
+  return expr;
+}
+function buildReservationBody(cfg, estimate, defaultSubject, args) {
   validateNonNegative(estimate, "estimate");
   const ttlMs = cfg.ttlMs ?? DEFAULT_TTL_MS;
   validateTtlMs(ttlMs);
@@ -939,7 +948,8 @@ function buildReservationBody(cfg, estimate, defaultSubject) {
     "agent",
     "toolset"
   ]) {
-    const val = cfg[field] ?? defaultSubject[field];
+    const resolved = evaluateStringField(cfg[field], args);
+    const val = resolved ?? defaultSubject[field];
     if (val) {
       subject[field] = val;
     }
@@ -949,8 +959,8 @@ function buildReservationBody(cfg, estimate, defaultSubject) {
   }
   validateSubject(subject);
   const action = {
-    kind: cfg.actionKind ?? "unknown",
-    name: cfg.actionName ?? "unknown"
+    kind: evaluateStringField(cfg.actionKind, args) ?? "unknown",
+    name: evaluateStringField(cfg.actionName, args) ?? "unknown"
   };
   if (cfg.actionTags) {
     action.tags = cfg.actionTags;
@@ -962,7 +972,7 @@ function buildReservationBody(cfg, estimate, defaultSubject) {
     action,
     estimate: { unit, amount: estimate },
     ttl_ms: ttlMs,
-    overage_policy: cfg.overagePolicy ?? "REJECT"
+    overage_policy: cfg.overagePolicy ?? "ALLOW_IF_AVAILABLE"
   };
   validateGracePeriodMs(cfg.gracePeriodMs);
   if (cfg.gracePeriodMs !== void 0) {
@@ -1005,7 +1015,12 @@ var AsyncCyclesLifecycle = class {
   }
   async execute(fn, args, cfg) {
     const estimate = evaluateAmount(cfg.estimate, args);
-    const createBody = buildReservationBody(cfg, estimate, this._defaultSubject);
+    const createBody = buildReservationBody(
+      cfg,
+      estimate,
+      this._defaultSubject,
+      args
+    );
     const resResponse = await this._client.createReservation(createBody);
     if (!resResponse.isSuccess) {
       throw buildProtocolException("Failed to create reservation", resResponse);
@@ -1284,7 +1299,7 @@ async function reserveForStream(options) {
     actionTags,
     ttlMs = DEFAULT_TTL_MS,
     gracePeriodMs,
-    overagePolicy = "REJECT",
+    overagePolicy = "ALLOW_IF_AVAILABLE",
     dimensions
   } = options;
   validateNonNegative(estimate, "estimate");

package/dist/index.d.cts

@@ -76,12 +76,15 @@ declare enum ErrorCode {
     FORBIDDEN = "FORBIDDEN",
     NOT_FOUND = "NOT_FOUND",
     BUDGET_EXCEEDED = "BUDGET_EXCEEDED",
+    BUDGET_FROZEN = "BUDGET_FROZEN",
+    BUDGET_CLOSED = "BUDGET_CLOSED",
     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",
+    MAX_EXTENSIONS_EXCEEDED = "MAX_EXTENSIONS_EXCEEDED",
     INTERNAL_ERROR = "INTERNAL_ERROR",
     UNKNOWN = "UNKNOWN"
 }
@@ -213,6 +216,7 @@ interface DecisionResponse {
 interface EventCreateResponse {
     status: EventStatus;
     eventId: string;
+    charged?: Amount;
     balances?: Balance[];
 }
 interface DryRunResult {
@@ -338,20 +342,20 @@ declare class CyclesClient {
 interface WithCyclesConfig<TArgs extends unknown[] = unknown[], TResult = unknown> {
     estimate: number | ((...args: TArgs) => number);
     actual?: number | ((result: TResult) => number);
-    actionKind?: string;
-    actionName?: string;
+    actionKind?: string | ((...args: TArgs) => string | undefined);
+    actionName?: string | ((...args: TArgs) => string | undefined);
     actionTags?: string[];
     unit?: string;
     ttlMs?: number;
     gracePeriodMs?: number;
     overagePolicy?: string;
     dryRun?: boolean;
-    tenant?: string;
-    workspace?: string;
-    app?: string;
-    workflow?: string;
-    agent?: string;
-    toolset?: string;
+    tenant?: string | ((...args: TArgs) => string | undefined);
+    workspace?: string | ((...args: TArgs) => string | undefined);
+    app?: string | ((...args: TArgs) => string | undefined);
+    workflow?: string | ((...args: TArgs) => string | undefined);
+    agent?: string | ((...args: TArgs) => string | undefined);
+    toolset?: string | ((...args: TArgs) => string | undefined);
     dimensions?: Record<string, string>;
     useEstimateIfActualNotProvided?: boolean;
 }

package/dist/index.d.ts

@@ -76,12 +76,15 @@ declare enum ErrorCode {
     FORBIDDEN = "FORBIDDEN",
     NOT_FOUND = "NOT_FOUND",
     BUDGET_EXCEEDED = "BUDGET_EXCEEDED",
+    BUDGET_FROZEN = "BUDGET_FROZEN",
+    BUDGET_CLOSED = "BUDGET_CLOSED",
     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",
+    MAX_EXTENSIONS_EXCEEDED = "MAX_EXTENSIONS_EXCEEDED",
     INTERNAL_ERROR = "INTERNAL_ERROR",
     UNKNOWN = "UNKNOWN"
 }
@@ -213,6 +216,7 @@ interface DecisionResponse {
 interface EventCreateResponse {
     status: EventStatus;
     eventId: string;
+    charged?: Amount;
     balances?: Balance[];
 }
 interface DryRunResult {
@@ -338,20 +342,20 @@ declare class CyclesClient {
 interface WithCyclesConfig<TArgs extends unknown[] = unknown[], TResult = unknown> {
     estimate: number | ((...args: TArgs) => number);
     actual?: number | ((result: TResult) => number);
-    actionKind?: string;
-    actionName?: string;
+    actionKind?: string | ((...args: TArgs) => string | undefined);
+    actionName?: string | ((...args: TArgs) => string | undefined);
     actionTags?: string[];
     unit?: string;
     ttlMs?: number;
     gracePeriodMs?: number;
     overagePolicy?: string;
     dryRun?: boolean;
-    tenant?: string;
-    workspace?: string;
-    app?: string;
-    workflow?: string;
-    agent?: string;
-    toolset?: string;
+    tenant?: string | ((...args: TArgs) => string | undefined);
+    workspace?: string | ((...args: TArgs) => string | undefined);
+    app?: string | ((...args: TArgs) => string | undefined);
+    workflow?: string | ((...args: TArgs) => string | undefined);
+    agent?: string | ((...args: TArgs) => string | undefined);
+    toolset?: string | ((...args: TArgs) => string | undefined);
     dimensions?: Record<string, string>;
     useEstimateIfActualNotProvided?: boolean;
 }

package/dist/index.js

@@ -760,12 +760,15 @@ var ErrorCode = /* @__PURE__ */ ((ErrorCode2) => {
   ErrorCode2["FORBIDDEN"] = "FORBIDDEN";
   ErrorCode2["NOT_FOUND"] = "NOT_FOUND";
   ErrorCode2["BUDGET_EXCEEDED"] = "BUDGET_EXCEEDED";
+  ErrorCode2["BUDGET_FROZEN"] = "BUDGET_FROZEN";
+  ErrorCode2["BUDGET_CLOSED"] = "BUDGET_CLOSED";
   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["MAX_EXTENSIONS_EXCEEDED"] = "MAX_EXTENSIONS_EXCEEDED";
   ErrorCode2["INTERNAL_ERROR"] = "INTERNAL_ERROR";
   ErrorCode2["UNKNOWN"] = "UNKNOWN";
   return ErrorCode2;
@@ -851,7 +854,13 @@ function evaluateActual(expr, result, estimate, useEstimateFallback) {
     "actual expression is required when useEstimateIfActualNotProvided is false"
   );
 }
-function buildReservationBody(cfg, estimate, defaultSubject) {
+function evaluateStringField(expr, args) {
+  if (typeof expr === "function") {
+    return expr(...args);
+  }
+  return expr;
+}
+function buildReservationBody(cfg, estimate, defaultSubject, args) {
   validateNonNegative(estimate, "estimate");
   const ttlMs = cfg.ttlMs ?? DEFAULT_TTL_MS;
   validateTtlMs(ttlMs);
@@ -864,7 +873,8 @@ function buildReservationBody(cfg, estimate, defaultSubject) {
     "agent",
     "toolset"
   ]) {
-    const val = cfg[field] ?? defaultSubject[field];
+    const resolved = evaluateStringField(cfg[field], args);
+    const val = resolved ?? defaultSubject[field];
     if (val) {
       subject[field] = val;
     }
@@ -874,8 +884,8 @@ function buildReservationBody(cfg, estimate, defaultSubject) {
   }
   validateSubject(subject);
   const action = {
-    kind: cfg.actionKind ?? "unknown",
-    name: cfg.actionName ?? "unknown"
+    kind: evaluateStringField(cfg.actionKind, args) ?? "unknown",
+    name: evaluateStringField(cfg.actionName, args) ?? "unknown"
   };
   if (cfg.actionTags) {
     action.tags = cfg.actionTags;
@@ -887,7 +897,7 @@ function buildReservationBody(cfg, estimate, defaultSubject) {
     action,
     estimate: { unit, amount: estimate },
     ttl_ms: ttlMs,
-    overage_policy: cfg.overagePolicy ?? "REJECT"
+    overage_policy: cfg.overagePolicy ?? "ALLOW_IF_AVAILABLE"
   };
   validateGracePeriodMs(cfg.gracePeriodMs);
   if (cfg.gracePeriodMs !== void 0) {
@@ -930,7 +940,12 @@ var AsyncCyclesLifecycle = class {
   }
   async execute(fn, args, cfg) {
     const estimate = evaluateAmount(cfg.estimate, args);
-    const createBody = buildReservationBody(cfg, estimate, this._defaultSubject);
+    const createBody = buildReservationBody(
+      cfg,
+      estimate,
+      this._defaultSubject,
+      args
+    );
     const resResponse = await this._client.createReservation(createBody);
     if (!resResponse.isSuccess) {
       throw buildProtocolException("Failed to create reservation", resResponse);
@@ -1209,7 +1224,7 @@ async function reserveForStream(options) {
     actionTags,
     ttlMs = DEFAULT_TTL_MS,
     gracePeriodMs,
-    overagePolicy = "REJECT",
+    overagePolicy = "ALLOW_IF_AVAILABLE",
     dimensions
   } = options;
   validateNonNegative(estimate, "estimate");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runcycles",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "TypeScript client for the Cycles budget-management protocol",
   "license": "Apache-2.0",
   "author": "runcycles",
@@ -8,7 +8,7 @@
     "type": "git",
     "url": "https://github.com/runcycles/cycles-client-typescript.git"
   },
-  "homepage": "https://github.com/runcycles/cycles-client-typescript#readme",
+  "homepage": "https://runcycles.io",
   "bugs": {
     "url": "https://github.com/runcycles/cycles-client-typescript/issues"
   },
@@ -20,7 +20,14 @@
     "api-client",
     "ai",
     "llm",
-    "runcycles"
+    "runcycles",
+    "cost-control",
+    "governance",
+    "agents",
+    "anthropic",
+    "openai",
+    "token-budget",
+    "spend-limit"
   ],
   "type": "module",
   "main": "./dist/index.cjs",
@@ -56,14 +63,17 @@
     "prepublishOnly": "npm run lint && npm run build"
   },
   "devDependencies": {
-    "@types/node": "^22.19.15",
-    "@typescript-eslint/eslint-plugin": "^8.57.0",
-    "@typescript-eslint/parser": "^8.57.0",
+    "@types/node": "^25.5.0",
+    "@typescript-eslint/eslint-plugin": "^8.58.0",
+    "@typescript-eslint/parser": "^8.58.0",
     "@vitest/coverage-v8": "^4.1.0",
+    "ajv": "^8.18.0",
+    "ajv-formats": "^3.0.1",
     "eslint": "^10.0.3",
     "tsup": "^8.0.0",
-    "typescript": "^5.9.3",
-    "vite": "^6.4.1",
-    "vitest": "^4.1.0"
+    "typescript": "^6.0.2",
+    "vite": "^8.0.3",
+    "vitest": "^4.1.0",
+    "yaml": "^2.8.3"
   }
 }