runcycles 0.2.0 → 0.3.1

package/README.md

@@ -1,12 +1,14 @@
 [![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
+# Cycles TypeScript Client — AI agent budget and action authority SDK
 
-TypeScript client for the [Cycles](https://runcycles.io) budget-management protocol — govern spend on AI calls, API usage, and any metered resource.
+**TypeScript/Node.js SDK for AI agent budget governance — enforce cost limits, tool permissions, and multi-tenant policies before LLM calls or agent actions execute.** Works with OpenAI, Anthropic, MCP servers, OpenAI Agents SDK, LangChain.js, and any Node.js agent runtime.
 
-Cycles lets you set budgets, reserve capacity before expensive operations, and track actual usage. This client handles the full reservation lifecycle: reserve budget up front, execute your work, then commit or release — with automatic heartbeats, retries, and typed error handling.
+Higher-order function and `AsyncLocalStorage`-based API for the [Cycles Protocol](https://github.com/runcycles/cycles-protocol): reserve capacity before expensive operations, execute your work, commit or release — with automatic heartbeats, retries, and typed error handling. Install via `npm install runcycles`.
 
 ## Requirements
 
@@ -314,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
@@ -328,13 +330,13 @@ interface WithCyclesConfig {
   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
@@ -342,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()`:

package/dist/index.cjs

@@ -929,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);
@@ -942,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;
     }
@@ -952,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;
@@ -1008,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);

package/dist/index.d.cts

@@ -342,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

@@ -342,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

@@ -854,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);
@@ -867,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;
     }
@@ -877,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;
@@ -933,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);

package/package.json

@@ -1,25 +1,43 @@
 {
   "name": "runcycles",
-  "version": "0.2.0",
-  "description": "TypeScript client for the Cycles budget-management protocol",
+  "version": "0.3.1",
+  "description": "TypeScript AI agent runtime control — enforce LLM cost limits, action permissions, and audit trails for agents before execution.",
   "license": "Apache-2.0",
   "author": "runcycles",
   "repository": {
     "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"
   },
   "keywords": [
+    "ai-agent",
+    "agent-budget",
+    "agent-governance",
+    "budget-control",
+    "cost-control",
+    "cost-enforcement",
+    "spending-limit",
+    "llm-cost",
+    "runtime-authority",
+    "action-control",
+    "action-authority",
+    "audit-trail",
+    "audit",
+    "compliance",
+    "multi-tenant",
+    "langchain",
+    "langgraph",
+    "openai-agents",
+    "vercel-ai-sdk",
+    "mcp",
+    "openai",
+    "anthropic",
+    "typescript-sdk",
+    "nodejs",
     "cycles",
-    "budget",
-    "billing",
-    "metering",
-    "api-client",
-    "ai",
-    "llm",
     "runcycles"
   ],
   "type": "module",
@@ -56,14 +74,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"
   }
 }