Skip to content

CHANGELOG.md

Latest commit

 

History

History
134 lines (81 loc) · 11.5 KB

CHANGELOG.md

File metadata and controls

134 lines (81 loc) · 11.5 KB
Raw

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog 1.1.0.

[Unreleased]

Added

  • TENANT_CLOSED error-code support per runtime spec v0.1.25.13 of cycles-protocol-v0.yaml (runcycles/cycles-protocol#125): servers return HTTP 409 error=TENANT_CLOSED on reservation create/commit/release/extend when the owning tenant is CLOSED (mirrors governance spec Rule 2). New ErrorCode.TENANT_CLOSED enum member, TenantClosedError class (thrown at reservation time by withCycles / lifecycle / reserveForStream via buildProtocolException; commit-time client errors are handled/released internally by withCycles, and StreamReservation.commit() throws generic CyclesError — neither commit path throws typed protocol exceptions), and CyclesProtocolError.isTenantClosed() helper. Purely additive — before this change the unrecognized code produced a generic CyclesProtocolError with the raw errorCode: "TENANT_CLOSED" preserved and isRetryable() already false (409 < 500); errorCodeFromString mapped it to ErrorCode.UNKNOWN, which isRetryableErrorCode reports as retryable — now it maps to the typed, non-retryable member. The vendored spec fixture (pinned pre-v0.1.25.13) is intentionally untouched until the spec PR merges.
  • LIMIT_EXCEEDED error-code support per runtime spec v0.1.25.12 (revision 2026-07-04): HTTP 429 rate-limit responses (public evidence/JWKS endpoints) carry error=LIMIT_EXCEEDED plus Retry-After / X-RateLimit-Reset headers. New ErrorCode.LIMIT_EXCEEDED enum member in spec declaration order (after MAX_EXTENSIONS_EXCEEDED; TENANT_CLOSED relocated after it so the enum mirrors the spec exactly). Classified retryable by both isRetryableErrorCode and CyclesProtocolError.isRetryable() — 429 is transient and the spec instructs retry after the indicated delay; the status-based rule only covers ≥500, so the code-based classification carries it (this also preserves the prior errorCodeFromString → UNKNOWN → retryable fallback behavior). Enum-only by design, matching the BUDGET_FROZEN/BUDGET_CLOSED pattern: not a reservation-lifecycle denial, so no exception class or buildProtocolException mapping.
  • Retry-After header exposure: the client now captures the HTTP Retry-After header (how 429 rate-limit responses carry the delay per the spec) and exposes it as CyclesResponse.retryAfterMsHeader (seconds → ms; non-integer forms ignored gracefully). buildProtocolException falls back to it for retryAfterMs when the body carries no retry_after_ms field (body wins when both are present). No auto-retry behavior change — the delay is surfaced, not consumed.

Fixed

  • README error-handling docs no longer describe CyclesTransportError as thrown on network failure — the SDK never constructs it. Reservation-time transport failures surface as CyclesProtocolError with status: -1 (withCycles / reserveForStream) or as CyclesResponse with isTransportError / status: -1 (programmatic client); commit-time failures are retried in the background by withCycles, while StreamReservation.commit() throws and resets finalized for caller retry or release. The class remains exported for use in user code; a new "Transport failures (status -1)" README subsection documents the actual behavior.
  • examples/vercel-ai-sdk chat route no longer mixes AI SDK v4 and v5 APIs (it compiled under neither while package.json pins "ai": "^4.0.0"): now pure v4 — Message type and convertToCoreMessages replace v5's UIMessage / convertToModelMessages. runcycles usage unchanged.

Notes

  • The Fixed items are docs + example only; the Added item is a small additive library change (no wire-format change).

[0.3.3] - 2026-05-22

Wire-passthrough verification for expires_from/expires_to and finalized_from/finalized_to query params on listReservations. Implements cycles-protocol-v0.yaml revision 2026-05-22 (runcycles/cycles-protocol#98) on the client side; runcycles/cycles-server#163 ships the server impl. Closes the TypeScript-client side of runcycles/cycles-server#162.

Added

  • Regression test on client.listReservations confirming the four new ISO-8601 window params are URL-encoded and forwarded to the query string. The existing params?: Record<string, string> signature already accepted them — the test locks the contract so future tightening cannot drop them silently. Colons URL-encoded to %3A per native fetch + URLSearchParams behavior.

Notes

  • No protocol or wire-format change. Servers older than v0.1.25.21 silently ignore the new params per the additive-parameter guarantee in cycles-protocol-v0.yaml.
  • 317 tests pass; coverage 98.4% statements / 99.62% lines (gate ≥95% per CLAUDE.md).

[0.3.2] - 2026-05-21

Wire-passthrough verification for the new from / to query params on listReservations. Implements cycles-protocol-v0.yaml revision 2026-05-21 (runcycles/cycles-protocol#97) on the client side; runcycles/cycles-server#160 ships the server impl.

Added

  • Regression test on client.listReservations confirming that from / to ISO-8601 date-time params are URL-encoded and forwarded to the query string. The client's params?: Record<string, string> signature already accepted these — the test locks the contract so future tightening cannot drop them silently. Both colons are URL-encoded (from=2026-05-21T00%3A00%3A00Z).

Notes

  • No protocol or wire-format change. Servers older than v0.1.25.20 silently ignore the new params per the additive-parameter guarantee in cycles-protocol-v0.yaml.
  • 316 tests pass; coverage 98.4% statements / 99.62% lines (gate ≥95% per CLAUDE.md).

[0.3.1] - 2026-05-07

npm metadata refresh for category-search discovery. No code changes — bundle and runtime behavior are identical to 0.3.0.

Changed

  • package.json: rewrote description to lead with the cost / action / audit pillars ("TypeScript AI agent runtime control — enforce LLM cost limits, action permissions, and audit trails for agents before execution.") and expanded keywords from 15 to 26. Drops legacy keywords (billing, metering, api-client, ai, llm, agents, token-budget, spend-limit) in favor of category-search variants (ai-agent, agent-budget, budget-control, cost-enforcement, spending-limit, llm-cost, runtime-authority, action-control, action-authority, audit-trail, audit, compliance, multi-tenant) plus framework targeting (langchain, langgraph, openai-agents, vercel-ai-sdk, mcp).

[0.3.0] - 2026-04-27

Java parity: dynamic subject and action fields on withCycles.

Added

  • Dynamic subject + action fields on withCycles config — tenant, workspace, app, workflow, agent, toolset, actionKind, and actionName now accept (...args: TArgs) => string | undefined in addition to a static string. Callables are resolved against the wrapped function's per-call args; returning undefined falls through to the client-config default (subject) or "unknown" (action). Static strings unchanged. Java parity with cycles-spring-boot-starter#50. (#72)

[0.2.0] - 2026-03-24

Bug fixes, support 0.1.24 spec.

Added

  • Add badges to README for npm, CI, and license (#24)
  • Add documentation links section to README (#25)
  • Add budget and extension error codes, charged amount to event response (#29)

Changed

  • Document nested withCycles behavior and recommended patterns (#26)
  • Claude/analyze spring issue 29 v biy9 (#27)
  • Change default overage policy from REJECT to ALLOW_IF_AVAILABLE (#28)
  • chore: bump version to 0.2.0 for protocol v0.1.24 (#30)

[0.1.2] - 2026-03-19

Fix type safety in WithCyclesConfig generics.

Added

  • Add AUDIT.md documenting protocol conformance (#19)
  • Add AWS Bedrock and Google Gemini budget governance examples (#20)
  • Add parent README for examples directory (#21)
  • Add API key creation guide to documentation and examples (#22)

Fixed

  • Fix type safety in WithCyclesConfig generics and add compile-time type tests (#23)

[0.1.1] - 2026-03-13

Updates and bug and stability fixes, more SDK examples.

Added

  • Add manual workflow_dispatch trigger to CI publish (#4)
  • Add comprehensive test coverage for lifecycle, streaming, and error handling (#7)
  • Add comprehensive examples for Cycles budget governance (#9)
  • Claude/expand ai examples zj dwy (#10)
  • Add ESLint with typescript-eslint/recommended and coverage thresholds (#12)
  • Add lint and coverage enforcement to CI (#13)
  • Add test for commit retry exhaustion warning (#18)

Changed

  • Comprehensive README rewrite for npm publication (#5)
  • Optimize initialization and add async disposal support (#6)
  • Update TEST_COVERAGE_ANALYSIS.md with final coverage results (#8)
  • Document withCycles client caching behavior in default client section (#11)
  • Document commit rollback behavior for failed commits in streaming sec… (#14)
  • Warn on commit retry exhaustion in CommitRetryEngine (#15)

Removed

  • Remove dead code: unused constants, validateReservationId, makeClient (#16)
  • Remove CyclesTransportError from public exports (#17)

[0.1.0] - 2026-03-13

Initial release.

Added

  • Add TypeScript client for Cycles budget-management protocol (#1)
  • Add comprehensive mapper functions for wire format conversion (#2)
  • Add CI/CD pipeline and improve package metadata (#3)