adonis-ai-kit 0.0.0-stage → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,74 @@
+# Changelog
+
+All notable changes to `adonis-ai-kit` are documented in this file.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [1.2.0] - 2026-10-22
+
+Includes the work previously staged as the 1.3.0 and 1.4.0 candidates, which were never published.
+
+### Added
+
+- `adonis-ai-kit/models` subpath export:
+  - Types and helpers: `ResolvedModel`, `parseModelRef`, `modelKeyFor`, `breakerKeyFor`, `PROTOCOL_TO_NPM`, `resolveProviderNpm`.
+  - `ProviderFactory`, `BUILTIN_PROVIDER_EXPORTS` and `ProviderFactoryRegistry` (lazy import of known AI SDK provider packages, plus `register()` for custom ones).
+  - `LanguageModelFactory`: 180 s fetch timeout, secret-header redaction in logs, ACP models through `AcpDriver`, and `shutdown()`.
+  - `ModelResolver` and `CatalogModelResolver`.
+  - `buildChainCandidates`, `runModelChain` and `FallbackEvent` for running a call over an ordered model chain with per-credential circuit breakers.
+- `AcpDriverDeps.runtime`: a prebuilt runtime config for the ACP driver.
+- `AiManager` call options:
+  - `schema` (structured `output` on `generateText` and `streamText`), `stopWhen`, `maxRetries`, `onStepFinish`.
+  - `models` and `onFallback` to run a call over a dynamic model chain.
+- `AiConfig.resolver` and `AiConfig.languageModels`.
+- Optional `peerDependencies` for the AI SDK provider packages.
+- `LanguageModelFactory` options `acp.inheritEnv` (pass the full server environment to agents) and `acp.shareDriver` (set to `false` to give every model its own driver and agent process).
+- Single `Logger` type shared by all modules (`LoggerContract` stays as a deprecated alias).
+- `ErrorClassification.errorClass` and `ErrorClassification.countsAsFailure`, plus the `countsAsBreakerFailure()` helper.
+- `CircuitBreaker.acquire()` returning a `BreakerPermit`, and `CircuitBreaker.resetAll()`.
+- `ToolAccessOptions.permissions` for per-call tool permissions.
+- ACP: `AcpAgentConfig.credentialEnv` and `buildAcpRuntimeConfig(agentId, options)` with `projectMcpPath` (the positional form keeps working).
+- Error taxonomy exported from the package root: `ErrorClass` (11 classes), `classifyErrorClass()`, `isRetryableError()` and `getUserFriendlyMessage()`.
+- Replaceable ACP agent registry: `registerAcpAgent()`, `setAcpAgents()` and `resetAcpAgents()`, so an application can point an agent at the binary installed on the machine.
+- Catalog option `injectSystemProviders` (default `true`) to turn off the automatic injection of openai/anthropic/google; superseded within this release by `systemProviders` and kept as a deprecated alias.
+- Catalog: `systemProviders: { fallback, acp }` option (also available as `CatalogConfig.systemProviders`) to inject fallback and ACP providers independently.
+
+### Changed
+
+- Optional provider peer dependencies accept any version.
+- Behavior changes to be aware of:
+  - `prompt_too_long` and `no_output_generated` errors now fall back to the next provider but never open the circuit breaker.
+  - Errors recognised only through `isRetryable === true` fall back, but no longer count against the circuit breaker.
+  - `ErrorClassification` gained two required fields (`errorClass`, `countsAsFailure`). This only affects code that constructs the interface itself.
+  - `dist/` is no longer tracked in git (it is still built and shipped in the npm package).
+
+### Deprecated
+
+- `injectSystemProviders` (added earlier in this release, then superseded by `systemProviders`) — use `systemProviders`.
+- The `sourcecraft` and `freebuff` default ACP agents — they will be removed from the defaults in 2.0; register them with `registerAcpAgent()`.
+- `LoggerContract` — use `Logger`.
+
+### Fixed
+
+- `ToolDefinition.description` accepts the AI SDK v7 tool description type (string or function); the confirmation action falls back to the tool name.
+- One error taxonomy now drives both fallback and circuit-breaker decisions.
+- HTTP status codes are found in `status`, `response.status`, nested `cause` and `lastError` (AI SDK `RetryError`).
+- HTTP 409 and 425 are classified as `overloaded`.
+- ACP agents registered with `setAcpAgents()`/`registerAcpAgent()` without `credentialEnv` inherit the built-in agent's credentials for the same id; `credentialEnv: []` opts out.
+- `CircuitBreaker.execute()` frees its probe slot even if `isFailure` throws.
+- Model chains fall through to the next candidate on missing provider packages, config errors and open breakers (without counting against the breaker), and reject a missing resolver up front.
+- Rejections of an async `onFallback` handler are caught and logged.
+- ACP models in `AiManager` chains use its `ConfirmationService`.
+- `AcpDriver` blanks `process.env` keys that are missing from a custom env source.
+- `LanguageModelFactory` with `acp.shareDriver: false` no longer retains a driver per call: the driver is released when its call ends.
+
+### Notes
+
+- An exhausted `models` chain rethrows the last error (or `ProviderUnavailableError` if no candidate could be attempted), unlike the provider cascade, which throws `CascadingFallbackError`.
+
+### Development
+
+- Japa test harness.
+
+## [1.1.0]
+
+Initial public release.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 IvanGlazyrin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,398 @@
-# Temporary Holding Version
+# adonis-ai-kit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **Production-grade AI & Agentic workflow toolkit for AdonisJS 7**, powered by Vercel AI SDK v7, multi-provider cascading fallback, circuit breakers, tool security guardrails, token budget tracking, models.dev live catalog, and ACP (Agent Client Protocol) coding agents.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![npm](https://img.shields.io/npm/v/adonis-ai-kit.svg)](https://www.npmjs.com/package/adonis-ai-kit)
+[![AdonisJS](https://img.shields.io/badge/AdonisJS-7.x-5A45FF.svg)](https://adonisjs.com)
+[![TypeScript](https://img.shields.io/badge/TypeScript-ES2022%20%2F%20NodeNext-blue.svg)](https://www.typescriptlang.org)
+[![Vercel AI SDK](https://img.shields.io/badge/Vercel%20AI%20SDK-v7.x-black.svg)](https://sdk.vercel.ai)
+[![Node](https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen.svg)](https://nodejs.org)
+
+---
+
+## Highlights & Architectural Comparison
+
+While frameworks like **Laravel AI** and **Prism** bring basic prompt-level abstractions to PHP, enterprise production systems require strict SRE resilience, tool execution guardrails, cost guarantees, and streaming protocol integrity. **`adonis-ai-kit`** is built from the ground up for high-concurrency Node.js microservices:
+
+| Feature | `adonis-ai-kit` (AdonisJS 7) | Laravel AI / Prism (PHP) |
+| :--- | :--- | :--- |
+| **Foundation Engine** | **Vercel AI SDK v7** (native Node.js async streams & tool calls) | Custom cURL/Guzzle wrappers |
+| **Circuit Breaker** | **Per `provider:model` key** (isolated half-open state, probe limits) | Global or none |
+| **Cascading Fallbacks** | **Safe**: never replays side-effects if tool calls already started | Retries from scratch (risk of double actions) |
+| **Tool Security (Guardrails)** | **Fail-closed** with Human-in-the-Loop (HITL), concurrent slots | Basic parameter mapping |
+| **Token Budget & Cost** | **Live USD pricing**, ring-buffer memory, cache-read & reasoning tokens | Raw token count or static tables |
+| **Catalog Auto-Discovery** | **models.dev integration** with TTL cache & atomic writes | Static configuration files |
+| **Agent Protocols** | **ACP (Agent Client Protocol)** for Claude Code, opencode & subagents | Basic prompt templates |
+| **HTTP Streaming** | **`response.streamAI()` macro** with heartbeats, SSE frames & client-abort hook | PHP chunked response buffers |
+
+---
+
+## Architecture Overview
+
+```mermaid
+flowchart TD
+    UserApp["AdonisJS Controller / Service"] --> AiManager["AiManager (Singleton Service)"]
+    
+    subgraph SRE_Resilience ["SRE Resilience & Fallback Layer"]
+        AiManager --> CircuitBreaker["Circuit Breaker (provider:model)"]
+        CircuitBreaker --> FallbackCascade["Cascading Provider Fallback"]
+    end
+    
+    subgraph Execution_Layer ["Execution & Agent Layer"]
+        FallbackCascade --> Providers["LLM Drivers (OpenAI, Anthropic, Google, Groq, ACP)"]
+        FallbackCascade --> AgentRunner["AgentRunner (Manifest + Skills)"]
+        AgentRunner --> ToolRegistry["Tool Registry (PolicyGuard)"]
+        ToolRegistry --> HITL["ConfirmationService (Human-in-the-Loop)"]
+    end
+
+    subgraph Observability_Cost ["Observability & Governance"]
+        Providers --> CostTracker["CostTracker (Ring Buffer)"]
+        Providers --> BudgetEnforcer["BudgetEnforcer (Atomic Reservations)"]
+        AiManager -.-> ModelsDev["models.dev Catalog (Live Pricing & Limits)"]
+    end
+
+    subgraph Transport_Layer ["Transport Layer"]
+        AiManager --> SSE["response.streamAI() Macro (SSE / Heartbeats / Abort)"]
+    end
+```
+
+---
+
+## Installation
+
+```bash
+npm install adonis-ai-kit
+# or
+pnpm add adonis-ai-kit
+```
+
+> Package name on npm is `adonis-ai-kit` (the `adonis-ai` name on npm is taken by another project).
+> The source repository is [github.com/IvanGlazyrin/adonis-ai-kit](https://github.com/IvanGlazyrin/adonis-ai-kit).
+
+Add the provider to `adonisrc.ts`:
+
+```ts
+export default defineConfig({
+  providers: [
+    // ...
+    () => import('adonis-ai-kit/providers/ai_provider')
+  ]
+})
+```
+
+Configure your providers in `config/ai.ts`:
+
+```ts
+import env from '#start/env'
+import { defineConfig } from 'adonis-ai-kit'
+
+export default defineConfig({
+  default: 'openai',
+  providers: {
+    openai: {
+      driver: 'openai',
+      apiKey: env.get('OPENAI_API_KEY'),
+      defaultModel: 'gpt-4o',
+    },
+    anthropic: {
+      driver: 'anthropic',
+      apiKey: env.get('ANTHROPIC_API_KEY'),
+      defaultModel: 'claude-3-7-sonnet-20250219',
+    },
+  },
+  // Automatically fallback to Anthropic if OpenAI is throttled (429) or down (5xx)
+  fallbackCascade: ['anthropic'],
+  circuitBreaker: {
+    failureThreshold: 5,
+    recoveryTimeoutMs: 30_000,
+    halfOpenMaxAttempts: 2,
+  },
+})
+```
+
+---
+
+## Core Capabilities
+
+### 1. Basic Generation & Multi-Provider Fallback
+
+Generate text with automatic token usage tracking and USD calculation:
+
+```ts
+import ai from 'adonis-ai-kit/services/main'
+
+const result = await ai.generateText({
+  prompt: 'Explain vector indexing in 3 sentences',
+})
+
+console.log(result.text)
+console.log(`Duration: ${result.durationMs}ms, Cost: $${result.costUsd}`)
+console.log(`Tokens: in=${result.usage.inputTokens}, out=${result.usage.outputTokens}, cached=${result.usage.cacheReadTokens}`)
+```
+
+If OpenAI returns `429 Rate Limit` or `503 Service Unavailable`, `adonis-ai-kit` automatically routes the request to `anthropic` with its configured model, recording circuit breaker metrics. A `prompt_too_long` failure also moves on to the next model, but never counts against (or opens) the circuit breaker.
+
+---
+
+### 2. Structured Output with Zod Schema
+
+```ts
+import { z } from 'zod'
+import ai from 'adonis-ai-kit/services/main'
+
+const resumeSchema = z.object({
+  fullName: z.string(),
+  skills: z.array(z.string()),
+  yearsOfExperience: z.number(),
+})
+
+const { object } = await ai.generateObject({
+  prompt: 'Extract candidate details: Ivan Glazyrin, 9 years in TS and Go',
+  schema: resumeSchema,
+})
+
+console.log(object.skills) // ['TypeScript', 'Go', ...]
+```
+
+---
+
+### 3. Server-Sent Events (SSE) Streaming in AdonisJS Controllers
+
+Use the built-in `response.streamAI()` macro:
+
+```ts
+import type { HttpContext } from '@adonisjs/core/http'
+import ai from 'adonis-ai-kit/services/main'
+
+export default class ChatController {
+  async stream({ request, response }: HttpContext) {
+    const stream = await ai.streamText({
+      prompt: request.input('message'),
+      model: 'gpt-4o',
+    })
+
+    // Sets 'Content-Type: text/event-stream', sends heartbeat pings,
+    // and automatically calls stream.abort() if the client disconnects!
+    return response.streamAI(stream, {
+      heartbeatMs: 15_000,
+      mode: 'sse',
+    })
+  }
+}
+```
+
+#### Structured output with tools in a stream
+
+`schema`, `stopWhen`, `maxRetries` and `onStepFinish` work for both `generateText` and `streamText`:
+
+```ts
+import { stepCountIs } from 'ai'
+import { z } from 'zod'
+
+const stream = await ai.streamText({
+  prompt: 'Find the cheapest flight and summarise it.',
+  tools: { searchFlights },
+  schema: z.object({ airline: z.string(), priceUsd: z.number() }),
+  stopWhen: stepCountIs(6), // takes precedence over `maxSteps`
+  maxRetries: 0, // fail fast, let the fallback chain take over
+  onStepFinish: (step) => console.log('step done', step.finishReason),
+})
+
+for await (const part of stream.fullStream) {
+  // forward parts to the client...
+}
+const flight = await stream.output // parsed against the schema
+```
+
+---
+
+### 4. Tool Security Guardrails & Human-in-the-Loop (HITL)
+
+Prevent untrusted AI models from executing destructive operations:
+
+```ts
+import { ToolRegistry, ConfirmationService, PolicyGuard } from 'adonis-ai-kit/guard'
+import { tool } from 'ai'
+import { z } from 'zod'
+
+const confirmationService = new ConfirmationService({ timeoutMs: 60_000 })
+const registry = new ToolRegistry(confirmationService)
+
+// Define tools
+registry.register(
+  'deploy_service',
+  tool({
+    description: 'Deploy service to cluster',
+    parameters: z.object({ cluster: z.string(), service: z.string() }),
+    execute: async ({ cluster, service }) => `Deployed ${service} to ${cluster}`,
+  }),
+  { permission: 'ask', maxCallsPerSession: 1 } // Requires human confirmation!
+)
+
+// When the model calls 'deploy_service', confirmationService pauses execution,
+// emits a confirmation request event, and resumes only when approved!
+```
+
+---
+
+### 5. Cost Tracking & Atomic Token Budget Enforcement
+
+```ts
+import { CostTracker, BudgetEnforcer } from 'adonis-ai-kit/budget'
+
+const tracker = new CostTracker({ maxRecords: 10_000 })
+const enforcer = new BudgetEnforcer({
+  maxCostUsd: 100.0,
+  maxInputTokens: 5_000_000,
+  maxOutputTokens: 1_000_000,
+})
+
+// Atomic pre-flight reservation prevents concurrent race conditions
+const reservation = enforcer.reserve('user-session-42', { estimatedCostUsd: 0.05 })
+if (!reservation.allowed) {
+  throw new Error('Budget exceeded')
+}
+
+try {
+  // run LLM request...
+  enforcer.settle(reservation.reservationId, { costUsd: 0.038 })
+} catch (e) {
+  enforcer.release(reservation.reservationId)
+}
+```
+
+---
+
+### 6. ACP (Agent Client Protocol) Coding Agents
+
+Run subagents using local CLI tools like **Claude Code**, **opencode**, or custom ACP binaries with sanitized environments:
+
+```ts
+import { AgentRunner, AgentLoader } from 'adonis-ai-kit/agents'
+
+const loader = new AgentLoader({
+  configsDir: './resources/agent-configs',
+  skillsDir: './resources/agent-skills',
+})
+
+const runner = new AgentRunner(aiManager, registry, loader)
+const execution = await runner.run({
+  agentId: 'code-reviewer',
+  userPrompt: 'Audit packages/adonis-ai for race conditions',
+})
+```
+
+Agents declare the credentials they need and can receive a project MCP server explicitly:
+
+```ts
+import { registerAcpAgent, buildAcpRuntimeConfig } from 'adonis-ai-kit/acp'
+
+registerAcpAgent('my-agent', {
+  id: 'my-agent', name: 'My Agent', description: '', command: 'my-agent-acp', args: [],
+  envVarPrefix: 'ACP_MY_AGENT', supportsMcpServers: true,
+  // the first set source is passed to the agent process as `target`
+  credentialEnv: [{ target: 'MY_API_KEY', sources: ['MY_API_KEY', 'MY_KEY'] }],
+})
+
+const runtime = buildAcpRuntimeConfig('my-agent', {
+  projectMcpPath: './mcp/server.js', // used when ACP_MY_AGENT_PROJECT_MCP_PATH is unset
+  // the project MCP server is still only attached when ACP_MY_AGENT_ENABLE_PROJECT_MCP=true
+})
+```
+
+ACP agents in a `models` chain ask a human through the manager's `ConfirmationService` (see `getConfirmationService()`), like the provider cascade does.
+
+Calling `buildAcpRuntimeConfig` + `createACPProvider` directly bypasses the env sanitizing that `AcpDriver` applies: the agent then inherits the full server environment.
+
+The `sourcecraft` and `freebuff` default agents are deprecated and will be removed from the defaults in 2.0; register them with `registerAcpAgent()` if you need them.
+
+---
+
+### 7. Dynamic Credentials & Model Chains
+
+Apps with per-user credentials can't use a static provider cascade. Pass `models` — an ordered chain of
+`ResolvedModel | string` — to `generateText`, `streamText` or `generateObject`; the provider cascade is then not used.
+
+```ts
+const result = await ai.generateText({
+  prompt: 'Summarize this',
+  models: [userKeyModel, teamKeyModel, 'anthropic/claude-sonnet-4-5'],
+  onFallback: ({ fromModel, toModel, errorClass }) => log.warn(`${fromModel} -> ${toModel} (${errorClass})`),
+})
+result.provider // providerID of the model that answered
+result.model    // its modelID
+// fromModel / toModel are breaker keys: the credential key when the model has one, otherwise provider/model
+```
+
+- Entries are tried in order. Retryable failures (429, 5xx, network) and entries that cannot be attempted (missing provider
+  package, config error, open breaker) move on to the next entry; bad requests, caller aborts and any failure after a
+  tool has run are thrown as is. `streamText` falls back on errors before the first chunk.
+- Each entry has its own circuit breaker, keyed by `credentialKey` when present (so one bad key doesn't block the others).
+- String entries are resolved through `config.resolver` (e.g. a `CatalogModelResolver`); without one a `ProviderConfigError` is thrown.
+- Models are built by `config.languageModels` (a `LanguageModelFactory`); when absent a default one is created lazily.
+  `manager.shutdown()` shuts it down (stops ACP agents).
+- `schema`, `stopWhen`, `maxRetries` and `onStepFinish` work on the chain path too. Empty `models` uses the provider cascade.
+
+## Ace CLI Commands
+
+`adonis-ai-kit` registers helpful Ace commands:
+
+```bash
+# Test connectivity, latency, and model availability across configured providers
+node ace ai:test
+
+# Scaffold a new production agent prompt and schema
+node ace make:ai-agent backend-architect --mode=primary
+```
+
+---
+
+## Testing & Quality
+
+The package includes a comprehensive regression test suite with 100% pass rate:
+
+```bash
+npm run test:regression
+```
+
+- **Token Budget**: Rate calculations, cache-read discounts, reasoning token surcharges, ring-buffer bounded memory.
+- **Tool Guard**: Policy enforcement (`allow`, `ask`, `deny`), concurrency slots, fail-closed handlers, session validation.
+- **Adonis AI Core**: Cascading failovers without duplicate side-effects, SSE keepalive frames, models.dev live discovery & TTL, ACP command sanitization.
+
+---
+
+## Development & Release
+
+```bash
+git clone https://github.com/IvanGlazyrin/adonis-ai-kit.git
+cd adonis-ai-kit
+npm install
+npm run build
+npm run test:regression
+```
+
+Consume the local build from an AdonisJS app without publishing:
+
+```bash
+# in the app
+npm install ../path/to/adonis-ai-kit   # file: dependency
+# or globally
+cd ../adonis-ai-kit && npm link
+cd ../my-app && npm link adonis-ai-kit
+```
+
+Releases are published to npm by pushing a version tag:
+
+```bash
+npm version patch            # bumps package.json + tag v1.1.1
+git push --follow-tags       # .github/workflows/release.yml runs npm publish
+```
+
+The workflow requires an `NPM_TOKEN` secret in the repository settings.
+
+---
+
+## License
+
+MIT © [Ivan Glazyrin](https://github.com/IvanGlazyrin) (glazrus97@gmail.com)

package/dist/commands/ai_test.d.ts

@@ -0,0 +1,12 @@
+import { BaseCommand } from '@adonisjs/core/ace';
+import type { CommandOptions } from '@adonisjs/core/types/ace';
+export default class AiTestCommand extends BaseCommand {
+    static commandName: string;
+    static description: string;
+    static options: CommandOptions;
+    provider?: string;
+    model?: string;
+    testPrompt: string;
+    run(): Promise<void>;
+}
+//# sourceMappingURL=ai_test.d.ts.map

package/dist/commands/ai_test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai_test.d.ts","sourceRoot":"","sources":["../../commands/ai_test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAS,MAAM,oBAAoB,CAAA;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAE9D,MAAM,CAAC,OAAO,OAAO,aAAc,SAAQ,WAAW;IACpD,MAAM,CAAC,WAAW,SAAY;IAC9B,MAAM,CAAC,WAAW,SAA4E;IAE9F,MAAM,CAAC,OAAO,EAAE,cAAc,CAE7B;IAGO,QAAQ,CAAC,EAAE,MAAM,CAAA;IAGjB,KAAK,CAAC,EAAE,MAAM,CAAA;IAOd,UAAU,EAAE,MAAM,CAAA;IAEpB,GAAG;CA4EV"}

package/dist/commands/ai_test.js

@@ -0,0 +1,98 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { BaseCommand, flags } from '@adonisjs/core/ace';
+export default class AiTestCommand extends BaseCommand {
+    static commandName = 'ai:test';
+    static description = 'Test connectivity, latency, and generation with configured AI providers';
+    static options = {
+        startApp: true,
+    };
+    async run() {
+        const ai = await this.app.container.make('ai');
+        this.ui.logger.info('🤖 Testing Adonis AI Provider Connectivity...\n');
+        const config = ai.getConfig();
+        const providersToTest = this.provider ? [this.provider] : Object.keys(config.providers);
+        if (providersToTest.length === 0) {
+            this.ui.logger.error('No AI providers configured in config/ai.ts!');
+            return;
+        }
+        const table = this.ui.table();
+        table.head(['Provider', 'Model', 'Status', 'Latency', 'Circuit Breaker', 'Cost ($)']);
+        for (const pName of providersToTest) {
+            const pConfig = config.providers[pName];
+            if (!pConfig) {
+                this.ui.logger.error(`Provider "${pName}" not found in config!`);
+                continue;
+            }
+            const testModel = this.model ?? pConfig.defaultModel ?? 'default';
+            const start = Date.now();
+            try {
+                const response = await ai.generateText({
+                    provider: pName,
+                    model: this.model,
+                    prompt: this.testPrompt || "Respond with PONG and your model identity in 10 words or less.",
+                    maxOutputTokens: 50,
+                    agentName: 'ace-ai-test',
+                });
+                const latency = Date.now() - start;
+                const stats = ai.getCircuitBreaker().getStats(`${response.provider}:${response.model}`);
+                // A fallback provider answering is NOT a pass for the provider under test
+                const answeredByFallback = response.provider !== pName;
+                table.row([
+                    this.colors.cyan(pName),
+                    response.model,
+                    answeredByFallback
+                        ? this.colors.yellow(`⚠ FALLBACK (${response.provider})`)
+                        : this.colors.green('✔ OK'),
+                    `${latency}ms`,
+                    this.colors.green(stats.state.toUpperCase()),
+                    response.costUsd !== undefined ? `$${response.costUsd.toFixed(6)}` : 'N/A',
+                ]);
+                this.ui.logger.info(`[${pName}] Output: "${response.text.trim()}"`);
+            }
+            catch (err) {
+                const latency = Date.now() - start;
+                const stats = ai.getCircuitBreaker().getStats(`${pName}:${testModel}`);
+                table.row([
+                    this.colors.cyan(pName),
+                    testModel,
+                    this.colors.red('✖ FAILED'),
+                    `${latency}ms`,
+                    this.colors.red(stats.state.toUpperCase()),
+                    'N/A',
+                ]);
+                this.ui.logger.error(`[${pName}] Error: ${err.message}`);
+            }
+        }
+        this.ui.logger.log('');
+        table.render();
+        this.ui.logger.log('');
+        const totalCost = ai.getCostTracker().getTotalCost();
+        const totalTokens = ai.getCostTracker().getTotalTokens();
+        this.ui.logger.info(`Total session cost: ${totalCost.toFixed(6)} | Tokens: ${totalTokens}`);
+    }
+}
+__decorate([
+    flags.string({ description: 'Specific provider to test (e.g. openai, anthropic, gemini, groq, ollama)' }),
+    __metadata("design:type", String)
+], AiTestCommand.prototype, "provider", void 0);
+__decorate([
+    flags.string({ description: 'Model to test with' }),
+    __metadata("design:type", String)
+], AiTestCommand.prototype, "model", void 0);
+__decorate([
+    flags.string({
+        name: 'prompt',
+        description: 'Test prompt to send',
+        default: 'Respond with "PONG" and your model identity in 10 words or less.',
+    }),
+    __metadata("design:type", String)
+], AiTestCommand.prototype, "testPrompt", void 0);
+//# sourceMappingURL=ai_test.js.map

package/dist/commands/ai_test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai_test.js","sourceRoot":"","sources":["../../commands/ai_test.ts"],"names":[],"mappings":"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"}

package/dist/commands/main.d.ts

@@ -0,0 +1,14 @@
+import type { CommandMetaData } from '@adonisjs/core/types/ace';
+import type { BaseCommand } from '@adonisjs/core/ace';
+type CommandClass = typeof BaseCommand;
+/**
+ * Ace command loader contract: returns metadata of every command in this package.
+ * Metadata is derived from the command classes themselves, so no generated `commands.json` is needed.
+ */
+export declare function getMetaData(): Promise<CommandMetaData[]>;
+/**
+ * Ace command loader contract: resolves the command class for the given metadata.
+ */
+export declare function getCommand(metaData: Pick<CommandMetaData, 'commandName'>): Promise<CommandClass | null>;
+export {};
+//# sourceMappingURL=main.d.ts.map

package/dist/commands/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../commands/main.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAA;AAC/D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAErD,KAAK,YAAY,GAAG,OAAO,WAAW,CAAA;AActC;;;GAGG;AACH,wBAAsB,WAAW,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC,CAM9D;AAED;;GAEG;AACH,wBAAsB,UAAU,CAAC,QAAQ,EAAE,IAAI,CAAC,eAAe,EAAE,aAAa,CAAC,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAG7G"}

package/dist/commands/main.js

@@ -0,0 +1,31 @@
+const loaders = [
+    () => import('./ai_test.js'),
+    () => import('./make_agent.js'),
+];
+let cachedMetaData;
+const cachedCommands = new Map();
+async function loadAll() {
+    return Promise.all(loaders.map(async (load) => (await load()).default));
+}
+/**
+ * Ace command loader contract: returns metadata of every command in this package.
+ * Metadata is derived from the command classes themselves, so no generated `commands.json` is needed.
+ */
+export async function getMetaData() {
+    if (cachedMetaData)
+        return cachedMetaData;
+    const commands = await loadAll();
+    for (const command of commands)
+        cachedCommands.set(command.commandName, command);
+    cachedMetaData = commands.map((command) => command.serialize());
+    return cachedMetaData;
+}
+/**
+ * Ace command loader contract: resolves the command class for the given metadata.
+ */
+export async function getCommand(metaData) {
+    if (cachedCommands.size === 0)
+        await getMetaData();
+    return cachedCommands.get(metaData.commandName) ?? null;
+}
+//# sourceMappingURL=main.js.map