flowstate-ai-gateway-core Package Skill

Package: @epicdm/flowstate-ai-gateway-core Repository: epic-flowstate-community Path: packages/ai-gateway-core Version: 0.1.7

Use this published Dojo skill as the package-level entrypoint. For detailed workflows, use the package-local skills listed below.

Primary Package Workflow

FlowState AI Gateway Core

Use this skill for packages/ai-gateway-core, the shared core library for FlowState AI Gateway runtimes.

Package Identity

• This is a publishable library, not the running gateway service.
• Import from @epicdm/flowstate-ai-gateway-core; avoid deep imports unless working inside the package.
• Downstream service package: packages/flowstate-ai-gateway.
• Preferred handler API: handleProviderRequest.
• handleMessages is still exported for compatibility but should not be used for new guidance.

Source Map

• src/index.ts: public export surface.
• src/handler/messages.ts: provider request handling, accounting, budget enforcement, ledger append behavior.
• src/providers/*: adapters, wire-format behavior, translation, intentional stub providers.
• src/cost/prices.ts, src/cost/compute.ts: pricing, usage normalization, cost calculation.
• src/policy/budget.ts: daily budget checks, enforcement, and status.
• src/store/ledger-store.ts: ledger store interface and in-memory implementation.
• src/metadata/headers.ts: FlowState metadata header constants and sanitization.
• src/audit/payload.ts: request/response payload audit capture and merge helpers.
• src/streaming/sse.ts: Anthropic SSE usage tap.

Workflow: Provider Adapters

1. Implement or update the adapter under src/providers.
2. Preserve passthrough semantics: parse only what the core needs, and forward unknown request fields where the provider contract allows it.
3. Update adapterWireFormat when adding a new adapter key.
4. Add pricing aliases if the adapter introduces new model identifiers.
5. Export the adapter from src/index.ts only if it is public.
6. Add focused provider tests.

Workflow: Usage, Cost, And Budget

1. Normalize provider usage into the shared usage shape.
2. Compute cost with computeCost() and PRICES.
3. Treat PRICES as time-sensitive; verify source pricing before changing values.
4. Preserve warn-mode behavior after ledger append and enforce-mode behavior before provider call.
5. In enforce mode, unpriced successful traffic should fail closed according to current policy.
6. Keep budget decisions tied to trusted identity metadata supplied by the consuming runtime.

Workflow: Streaming And Translation

• Stream accounting settles after drain, cancel, or error; do not consume the body in a way that prevents downstream response streaming.
• OpenAI chat streaming may need stream_options.include_usage injected.
• Anthropic-to-OpenAI translation should preserve Anthropic-facing response shape.
• Unsupported Anthropic content blocks intentionally error; do not silently drop them.

Workflow: Payload Audit And Ledger

• Payload audit helpers compute hashes and optionally capture bodies without breaking downstream reads.
• LedgerStore.append() is used for stream-open rows and completion rows; consumers may see lifecycle rows rather than one row per request.
• Keep ledger row shape coordinated with downstream service persistence.
• Do not store raw payloads unless the caller explicitly enabled capture and provided the required audit key in the consuming service.

Guardrails

• Core parses metadata headers; the consuming app is responsible for HMAC verification and trust boundaries.
• Stub adapters intentionally throw ProviderNotImplemented; do not make them look production-ready without implementation and tests.
• Exact optional property and unchecked-index TypeScript settings make shape changes stricter than they may first appear.
• Treat generated .flowstate/dojo files as raw scaffolding until rebuilt from reviewed package skills.

Verification

yarn workspace @epicdm/flowstate-ai-gateway-core test
yarn workspace @epicdm/flowstate-ai-gateway-core typecheck
yarn workspace @epicdm/flowstate-ai-gateway-core build

When public behavior changes, also check the consuming gateway:

yarn nx build @epicdm/flowstate-ai-gateway

Package Skill Inventory

Skill Inventory: @epicdm/flowstate-ai-gateway-core

Package path: packages/ai-gateway-core.

Skillset

Composition Notes

• Use this package skill before changing packages/flowstate-ai-gateway, because the service consumes these core contracts.
• Use one skill for now; adapter/accounting/translation split skills can be added later if the package surface grows.
• Do not publish generated .flowstate/dojo content as the package skill.

Publication Readiness

Status: drafted, pending verification.

Before Dojo publication, rebuild package Dojo artifacts from this reviewed skill.

Review Gate

Package Skill Review: @epicdm/flowstate-ai-gateway-core

Package path: packages/ai-gateway-core.

Review Result

Status: drafted, source-backed, verified with one package-script lint blocker, pending publication.

The skillset is intentionally one dense operating skill covering provider adapters, request handling, accounting, budgets, audit, ledger, translation, and streaming.

Checks

• Source review: completed from package review agent output, package metadata, root exports, source layout, tests, downstream gateway references, and generated artifact drift.
• Skill inventory: completed.
• Skill files: completed.
• Verification: completed.
• Generated Dojo replacement: pending.
• Cloud Dojo publication: pending.

Verification Commands

Commands run:

yarn workspace @epicdm/flowstate-ai-gateway-core test
yarn workspace @epicdm/flowstate-ai-gateway-core typecheck
yarn workspace @epicdm/flowstate-ai-gateway-core build
yarn workspace @epicdm/flowstate-ai-gateway-core lint

Results:

• Skill file ASCII scan passed.
• Tests passed: 13 suites, 117 tests; Jest reported an open-handle warning after completion.
• Typecheck passed.
• Build passed.
• Lint did not run because the package script resolved eslint as missing: command not found: eslint.

Broader checks when public behavior changes:

yarn nx build @epicdm/flowstate-ai-gateway
rg "@epicdm/flowstate-ai-gateway-core" packages docker

Publication Gate

Do not publish existing .flowstate/dojo artifacts until they are rebuilt from reviewed package skills.

Start with this skill to understand the package purpose, then use the package-local focused skills for specific workflows. Keep this Dojo version aligned with packages/ai-gateway-core/package.json. Do not treat generated feature lists as lessons; use workflow evidence from CODE-REVIEW.md, SKILL-INVENTORY.md, and REVIEW.md.