@autobe/agent 0.16.0 → 0.17.1

package/src/context/AutoBeTokenUsage.ts

@@ -1,45 +1,232 @@
-import { AgenticaTokenUsage } from "@agentica/core";
 import { IAutoBeTokenUsageJson } from "@autobe/interface";
 
+import { AutoBeTokenUsageComponent } from "./AutoBeTokenUsageComponent";
 import { IAutoBeApplication } from "./IAutoBeApplication";
 
-export class AutoBeTokenUsage {
-  public readonly facade: AgenticaTokenUsage;
-  public readonly analyze: AgenticaTokenUsage;
-  public readonly prisma: AgenticaTokenUsage;
-  public readonly interface: AgenticaTokenUsage;
-  public readonly test: AgenticaTokenUsage;
-  public readonly realize: AgenticaTokenUsage;
+/**
+ * Comprehensive token usage tracker for the AutoBe vibe coding system.
+ *
+ * This class provides centralized tracking and management of token consumption
+ * across all AI agents in the automated development pipeline. It captures
+ * detailed token usage statistics for each processing phase - from initial
+ * requirements analysis through final implementation - enabling cost
+ * monitoring, performance optimization, and resource utilization analysis.
+ *
+ * The token usage data includes both input tokens (with cache efficiency) and
+ * output tokens (with generation type breakdowns), providing insights into AI
+ * processing efficiency and helping optimize the balance between computational
+ * costs and output quality.
+ *
+ * @author SunRabbit123
+ */
+export class AutoBeTokenUsage implements IAutoBeTokenUsageJson {
+  /**
+   * Token usage for the facade agent orchestrating the entire pipeline.
+   *
+   * Tracks tokens consumed by the initial agent that coordinates and manages
+   * the overall vibe coding process, including request parsing and response
+   * orchestration.
+   */
+  public readonly facade: AutoBeTokenUsageComponent;
 
-  public constructor(props?: IAutoBeTokenUsageJson) {
+  /**
+   * Token usage for the requirements analysis agent.
+   *
+   * Captures tokens used during the analysis phase where user requirements are
+   * processed, understood, and transformed into structured specifications for
+   * subsequent development phases.
+   */
+  public readonly analyze: AutoBeTokenUsageComponent;
+
+  /**
+   * Token usage for the Prisma database schema generation agent.
+   *
+   * Records tokens consumed while designing and generating database schemas,
+   * including entity relationships, field definitions, and database-specific
+   * optimizations.
+   */
+  public readonly prisma: AutoBeTokenUsageComponent;
+
+  /**
+   * Token usage for the API interface specification agent.
+   *
+   * Tracks tokens used in creating OpenAPI/Swagger specifications, defining
+   * endpoints, request/response structures, and API documentation.
+   */
+  public readonly interface: AutoBeTokenUsageComponent;
+
+  /**
+   * Token usage for the test code generation agent.
+   *
+   * Monitors tokens consumed during automated test creation, including scenario
+   * planning, test case generation, and end-to-end test implementation.
+   */
+  public readonly test: AutoBeTokenUsageComponent;
+
+  /**
+   * Token usage for the implementation realization agent.
+   *
+   * Captures tokens used in the final implementation phase where actual
+   * business logic, controllers, services, and integration code are generated.
+   */
+  public readonly realize: AutoBeTokenUsageComponent;
+
+  /**
+   * Aggregated token usage statistics across all agents.
+   *
+   * Provides a unified view of token consumption by combining data from all
+   * processing phases in the vibe coding pipeline. This computed property
+   * dynamically calculates the sum of all agent components (facade, analyze,
+   * prisma, interface, test, realize) whenever accessed, ensuring the aggregate
+   * always reflects the current state of token usage.
+   *
+   * The aggregation performs element-wise addition across all token metrics,
+   * including total counts, input breakdowns with cache statistics, and output
+   * categorizations by generation type. This comprehensive view enables overall
+   * cost assessment and resource utilization analysis for the entire automated
+   * development session.
+   */
+  public get aggregate(): IAutoBeTokenUsageJson.IComponent {
+    return AutoBeTokenUsage.keys()
+      .reduce(
+        (acc, cur) => AutoBeTokenUsageComponent.plus(acc, this[cur]),
+        new AutoBeTokenUsageComponent(),
+      )
+      .toJSON();
+  }
+
+  /* -----------------------------------------------------------
+    CONSTRUCTORS
+  ----------------------------------------------------------- */
+  /**
+   * Default Constructor.
+   *
+   * Creates a new token usage tracker with all agent phases initialized to
+   * empty components. Each component starts with zero values for all token
+   * counters, providing a clean slate for tracking token consumption from the
+   * beginning of a vibe coding session.
+   */
+  public constructor();
+
+  /**
+   * Binding Constructor.
+   *
+   * Creates a new instance that shares component references with the provided
+   * AutoBeTokenUsage instance. This establishes a bound relationship where both
+   * instances point to the same component objects. Any modifications to token
+   * counts through either instance will be reflected in both, enabling shared
+   * tracking across different contexts.
+   *
+   * @param bind Existing AutoBeTokenUsage instance to bind to
+   */
+  public constructor(bind: AutoBeTokenUsage);
+
+  /**
+   * Initializer Constructor.
+   *
+   * Reconstructs a token usage tracker from serialized JSON data. Creates new
+   * AutoBeTokenUsageComponent instances for each agent phase, initializing them
+   * with the corresponding values from the JSON structure. This enables
+   * restoration of token usage state from persisted data or transmission
+   * between different parts of the system.
+   *
+   * @param props Token usage data in JSON format
+   */
+  public constructor(props?: Omit<IAutoBeTokenUsageJson, "aggregate">);
+
+  public constructor(
+    props?: AutoBeTokenUsage | IAutoBeTokenUsageJson | undefined,
+  ) {
     if (props === undefined) {
-      this.facade = new AgenticaTokenUsage();
-      this.analyze = new AgenticaTokenUsage();
-      this.prisma = new AgenticaTokenUsage();
-      this.interface = new AgenticaTokenUsage();
-      this.test = new AgenticaTokenUsage();
-      this.realize = new AgenticaTokenUsage();
+      this.facade = new AutoBeTokenUsageComponent();
+      this.analyze = new AutoBeTokenUsageComponent();
+      this.prisma = new AutoBeTokenUsageComponent();
+      this.interface = new AutoBeTokenUsageComponent();
+      this.test = new AutoBeTokenUsageComponent();
+      this.realize = new AutoBeTokenUsageComponent();
       return;
+    } else if (props instanceof AutoBeTokenUsage) {
+      this.facade = props.facade;
+      this.analyze = props.analyze;
+      this.prisma = props.prisma;
+      this.interface = props.interface;
+      this.test = props.test;
+      this.realize = props.realize;
+    } else {
+      this.facade = new AutoBeTokenUsageComponent(props.facade);
+      this.analyze = new AutoBeTokenUsageComponent(props.analyze);
+      this.prisma = new AutoBeTokenUsageComponent(props.prisma);
+      this.interface = new AutoBeTokenUsageComponent(props.interface);
+      this.test = new AutoBeTokenUsageComponent(props.test);
+      this.realize = new AutoBeTokenUsageComponent(props.realize);
     }
+  }
 
-    this.facade = new AgenticaTokenUsage(props.facade);
-    this.analyze = new AgenticaTokenUsage(props.analyze);
-    this.prisma = new AgenticaTokenUsage(props.prisma);
-    this.interface = new AgenticaTokenUsage(props.interface);
-    this.test = new AgenticaTokenUsage(props.test);
-    this.realize = new AgenticaTokenUsage(props.realize);
+  /**
+   * Serialize token usage data to JSON format.
+   *
+   * Converts the internal token usage representation to the standardized
+   * IAutoBeTokenUsageJson format, suitable for persistence, transmission, or
+   * external analysis. The serialized data maintains the complete structure
+   * including all agent phases and detailed token breakdowns.
+   *
+   * @returns JSON representation of token usage statistics
+   */
+  public toJSON(): IAutoBeTokenUsageJson {
+    return {
+      aggregate: this.aggregate,
+      facade: this.facade.toJSON(),
+      analyze: this.analyze.toJSON(),
+      prisma: this.prisma.toJSON(),
+      interface: this.interface.toJSON(),
+      test: this.test.toJSON(),
+      realize: this.realize.toJSON(),
+    };
   }
 
+  /* -----------------------------------------------------------
+    OPERATORS
+  ----------------------------------------------------------- */
+  /**
+   * Record token usage for specific processing stages.
+   *
+   * Updates token consumption statistics for one or more agent phases based on
+   * the provided usage data. This method allows selective recording of token
+   * usage for specific stages, enabling fine-grained tracking during
+   * multi-phase processing or when certain agents are invoked multiple times.
+   *
+   * @example
+   *   ```ts
+   *   tokenUsage.record(
+   *     { total: 150, input: { total: 100, cached: 20 }, output: { total: 50, ... } },
+   *     ['analyze', 'prisma']
+   *   );
+   *   ```;
+   *
+   * @param usage - Token usage component data to record
+   * @param additionalStages - Array of stage names to update with the usage
+   *   data
+   */
   public record(
-    usage: AgenticaTokenUsage,
+    usage: IAutoBeTokenUsageJson.IComponent,
     additionalStages: (keyof IAutoBeApplication)[] = [],
   ) {
-    this.facade.increment(usage);
     additionalStages.forEach((stage) => {
       this[stage].increment(usage);
     });
   }
 
+  /**
+   * Increment current token usage with data from another instance.
+   *
+   * Adds token usage statistics from another AutoBeTokenUsage instance to this
+   * one, updating all agent phases simultaneously. This method is useful for
+   * combining token usage from parallel processing, multiple runs, or when
+   * aggregating statistics from distributed agent executions.
+   *
+   * @param usage - AutoBeTokenUsage instance to add to current statistics
+   * @returns This instance for method chaining
+   */
   public increment(usage: AutoBeTokenUsage) {
     AutoBeTokenUsage.keys().forEach((key) => {
       this[key].increment(usage[key]);
@@ -47,41 +234,52 @@ export class AutoBeTokenUsage {
     return this;
   }
 
+  /**
+   * Create a new instance combining token usage from two sources.
+   *
+   * Performs element-wise addition of token usage statistics from two
+   * AutoBeTokenUsage instances, creating a new instance with the combined
+   * totals. This static method is useful for aggregating token usage across
+   * multiple vibe coding sessions or when merging statistics from different
+   * execution contexts.
+   *
+   * @param usageA - First token usage instance
+   * @param usageB - Second token usage instance
+   * @returns New instance with combined token usage statistics
+   */
   public static plus(usageA: AutoBeTokenUsage, usageB: AutoBeTokenUsage) {
     return new AutoBeTokenUsage({
-      facade: AgenticaTokenUsage.plus(usageA.facade, usageB.facade),
-      analyze: AgenticaTokenUsage.plus(usageA.analyze, usageB.analyze),
-      prisma: AgenticaTokenUsage.plus(usageA.prisma, usageB.prisma),
-      interface: AgenticaTokenUsage.plus(usageA.interface, usageB.interface),
-      test: AgenticaTokenUsage.plus(usageA.test, usageB.test),
-      realize: AgenticaTokenUsage.plus(usageA.realize, usageB.realize),
+      facade: AutoBeTokenUsageComponent.plus(usageA.facade, usageB.facade),
+      analyze: AutoBeTokenUsageComponent.plus(usageA.analyze, usageB.analyze),
+      prisma: AutoBeTokenUsageComponent.plus(usageA.prisma, usageB.prisma),
+      interface: AutoBeTokenUsageComponent.plus(
+        usageA.interface,
+        usageB.interface,
+      ),
+      test: AutoBeTokenUsageComponent.plus(usageA.test, usageB.test),
+      realize: AutoBeTokenUsageComponent.plus(usageA.realize, usageB.realize),
     });
   }
 
-  public toJSON(): IAutoBeTokenUsageJson {
-    return {
-      facade: this.facade.toJSON(),
-      analyze: this.analyze.toJSON(),
-      prisma: this.prisma.toJSON(),
-      interface: this.interface.toJSON(),
-      test: this.test.toJSON(),
-      realize: this.realize.toJSON(),
-    };
-  }
-
-  /** @internal */
-  private static keys(): ("facade" | keyof IAutoBeApplication)[] {
-    return ["facade", "analyze", "prisma", "interface", "test", "realize"];
+  /**
+   * Get all agent phase keys for iteration.
+   *
+   * Returns a readonly array of all agent phase names used in the vibe coding
+   * system. This internal utility method ensures consistent iteration over all
+   * token usage components when performing operations like aggregation or
+   * serialization.
+   *
+   * @returns Readonly array of agent phase keys
+   * @internal
+   */
+  private static keys() {
+    return [
+      "facade",
+      "analyze",
+      "prisma",
+      "interface",
+      "test",
+      "realize",
+    ] as const;
   }
 }
-
-// /** Type check statements */
-// 1 as unknown as AutoBeTokenUsage satisfies {
-//   [key in "facade" | keyof IAutoBeApplication]: AgenticaTokenUsage;
-// };
-
-// 1 as unknown as IAutoBeTokenUsageJson satisfies {
-//   [key in "facade" | keyof IAutoBeApplication]: IAutoBeInternalTokenUsageJson;
-// };
-
-// 1 as unknown as IAutoBeInternalTokenUsageJson satisfies IAgenticaTokenUsageJson;

package/src/context/AutoBeTokenUsageComponent.ts

@@ -0,0 +1,180 @@
+import { IAutoBeTokenUsageJson } from "@autobe/interface";
+
+/**
+ * Token usage component for individual AI agents in the vibe coding pipeline.
+ *
+ * Represents detailed token consumption statistics for a specific processing
+ * phase (facade, analyze, prisma, interface, test, or realize). This class
+ * tracks both input and output token usage with granular breakdowns, enabling
+ * precise cost analysis and performance optimization for each agent.
+ *
+ * The component structure includes:
+ *
+ * - Total token count for quick cost calculations
+ * - Input token breakdown with cache efficiency metrics
+ * - Output token categorization by generation type
+ *
+ * This granular tracking helps identify optimization opportunities and
+ * understand the computational characteristics of each agent phase.
+ *
+ * @author SunRabbit123
+ */
+export class AutoBeTokenUsageComponent
+  implements IAutoBeTokenUsageJson.IComponent
+{
+  /**
+   * Detailed breakdown of input token consumption.
+   *
+   * Tracks how many tokens were processed as input to the AI agent, including:
+   *
+   * - Total input tokens processed
+   * - Cached tokens that were reused from previous operations
+   *
+   * The cache efficiency (cached/total ratio) indicates how well the system is
+   * reusing context across multiple invocations.
+   */
+  public readonly input: IAutoBeTokenUsageJson.IInput;
+
+  /**
+   * Detailed breakdown of output token generation.
+   *
+   * Categorizes generated tokens by their purpose and acceptance status:
+   *
+   * - Total output tokens generated
+   * - Reasoning tokens (internal processing)
+   * - Accepted prediction tokens (efficient generation)
+   * - Rejected prediction tokens (quality control overhead)
+   *
+   * These metrics help understand the AI's generation efficiency and the
+   * effectiveness of its predictive mechanisms.
+   */
+  public readonly output: IAutoBeTokenUsageJson.IOutput;
+
+  /**
+   * Total token count combining all input and output tokens.
+   *
+   * Represents the complete token consumption for this component, providing a
+   * single metric for overall resource utilization. This value is critical for
+   * cost calculations and comparing efficiency across different agents or
+   * processing phases.
+   */
+  public get total(): number {
+    return this.input.total + this.output.total;
+  }
+
+  /* -----------------------------------------------------------
+    CONSTRUCTORS
+  ----------------------------------------------------------- */
+  /**
+   * Default Constructor.
+   *
+   * Creates a new token usage component with all counters initialized to zero.
+   * Constructs fresh input and output objects with default values, providing a
+   * clean starting point for tracking token consumption in an agent phase.
+   */
+  public constructor();
+
+  /**
+   * Initializer Constructor.
+   *
+   * Creates a new component populated with existing token usage data. Directly
+   * assigns the provided values to instance properties, preserving the exact
+   * token counts and structure from the source data for accurate tracking
+   * continuation.
+   *
+   * @param props - Token usage data to initialize the component
+   */
+  public constructor(props: Omit<IAutoBeTokenUsageJson.IComponent, "total">);
+
+  public constructor(props?: Omit<IAutoBeTokenUsageJson.IComponent, "total">) {
+    if (props === undefined) {
+      this.input = { total: 0, cached: 0 };
+      this.output = {
+        total: 0,
+        reasoning: 0,
+        accepted_prediction: 0,
+        rejected_prediction: 0,
+      };
+      return;
+    }
+    this.input = props.input;
+    this.output = props.output;
+  }
+
+  /**
+   * Export token usage data as JSON.
+   *
+   * Converts the component's token usage statistics to the standardized
+   * IAutoBeTokenUsageJson.IComponent format. This serialization maintains the
+   * complete structure including total counts and detailed breakdowns for both
+   * input and output tokens.
+   *
+   * @returns JSON representation of the token usage component
+   */
+  public toJSON(): IAutoBeTokenUsageJson.IComponent {
+    return {
+      total: this.total,
+      input: this.input,
+      output: this.output,
+    };
+  }
+
+  /* -----------------------------------------------------------
+    OPERATORS
+  ----------------------------------------------------------- */
+  /**
+   * Add token usage data to current statistics.
+   *
+   * Increments all token counters in this component by the corresponding values
+   * from the provided component data. This method performs in-place updates,
+   * modifying the current instance rather than creating a new one.
+   *
+   * Updates include:
+   *
+   * - Total token count
+   * - Input tokens (both total and cached)
+   * - Output tokens (reasoning, accepted/rejected predictions)
+   *
+   * @param props - Token usage component data to add to current values
+   */
+  public increment(props: IAutoBeTokenUsageJson.IComponent) {
+    this.input.total += props.input.total;
+    this.input.cached += props.input.cached;
+    this.output.total += props.output.total;
+    this.output.reasoning += props.output.reasoning;
+    this.output.accepted_prediction += props.output.accepted_prediction;
+    this.output.rejected_prediction += props.output.rejected_prediction;
+  }
+
+  /**
+   * Create new component combining two token usage statistics.
+   *
+   * Performs element-wise addition of all token counters from two components,
+   * creating a new AutoBeTokenUsageComponent instance with the combined totals.
+   * This static method is useful for aggregating token usage across multiple
+   * agent invocations or combining statistics from parallel processing.
+   *
+   * @param a - First token usage component
+   * @param b - Second token usage component
+   * @returns New component with combined token statistics
+   */
+  public static plus(
+    a: AutoBeTokenUsageComponent,
+    b: AutoBeTokenUsageComponent,
+  ) {
+    return new AutoBeTokenUsageComponent({
+      input: {
+        total: a.input.total + b.input.total,
+        cached: a.input.cached + b.input.cached,
+      },
+      output: {
+        total: a.output.total + b.output.total,
+        reasoning: a.output.reasoning + b.output.reasoning,
+        accepted_prediction:
+          a.output.accepted_prediction + b.output.accepted_prediction,
+        rejected_prediction:
+          a.output.rejected_prediction + b.output.rejected_prediction,
+      },
+    });
+  }
+}

package/src/factory/createAutoBeApplication.ts

@@ -43,7 +43,7 @@ export const createAutoBeController = <Model extends ILlmSchema.Model>(props: {
           };
       },
       prisma: async (next) => {
-        const r = await orchestratePrisma(props.context)(next);
+        const r = await orchestratePrisma(props.context, next);
         if (r.type === "prisma")
           return {
             type: r.compiled.type,